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Section 1 Introduction 



The process of implementing RHYTHM Supply Chain Planner (SCP) to 
deliver the required behavior and business benefits is customization. To 
do this, an implementor is engaged in multiple tasks including: 

■ organizing the file directory structure that will hold the various ele- 
ments required by RHYTHM SCP servers and clients 

■ providing system files to define implementation-specific model fields, 
client profiles (reports), and so on 

■ providing reports files that specify the data and views available to each 
client 

■ specifying and implementing the mapping of data from external 
sources into RHYTHM SCP models and vice versa 

■ developing the necessary client interfaces (interactive or non-interac- 
tive) to perform planning functions on the RHYTHM SCP server 

■ adjusting interactive client interfaces to support end-user workflows 

The goal of the RHYTHM SCP Object Interaction Language User Man- 
ual is to provide "one-stop shopping" for implementors to find and learn 
what they need to perform these tasks. This manual consists of user and 
reference materials designed to supplement, but not replace, the 
RHYTHM SCP Model Reference Manual. 
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Object Interaction Language 



Introduction 



1.1 Object Interaction Language 

Object Interaction Language (OIL) is the primary tool for implementors 
of RHYTHM SCP, and as such, is the primary topic of this manual. 

OIL is an interpreted, functional language. Its functions and expressions 
are compiled and checked when read by RHYTHM SCP, and all expres- 
sions can be used interactively. OIL allows access to and manipulation of 
the model information residing on the server through its worksheets. OIL 
worksheets are designed to use the "spreadsheet" paradigm as established 
by other software packages. OIL maps to, and utilizes, RHYTHM SCP 
model definitions and their interrelationships. It also allows parameter- 
ization of interfaces: interfaces can be tied to types of models (e.g. SITE) 
rather than to specific instances of models (e.g. Joe's Site). 

OIL is a strongly typed programming language. All function invocations 
expect arguments of a definite type, and all results from expressions and 
function calls are of definite types. OIL provides utilities for conversion 
from one type to another. These utilities (built into the language) are both 
automatic and explicit. OIL optimizes the execution of routines based on 
the context of execution and the availability of the data. 
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Overview of OIL Elements 



1 .2 Overview of OIL Elements 



OIL provides various elements for computing data for display to you, and 
for presenting the data in different ways for you to view. Several of these 
elements are listed below: 

■ Reports 

■ Worksheets 

■ Layouts 

■ Functional Worksheets 

■ do_files 

1.2.1 Reports, Layouts, Worksheets: As OIL Elements 

A report is a mechanism that provides information about the RHYTHM 
SCP models running on the RHYTHM SCP engine. Each report is a con- 
tainer for one or more layouts. Each layout in a report describes the dis- 
play of data contained in a worksheet. 

A report can be thought of as a two-dimensional table of information. 
The Layouts describe rows and columns of the two-dimensional table. 
Layouts are arranged vertically or horizontally. Each layout is associated 
with exactly one worksheet which contains calculations for the data in the 
layout. Each element of a layout is called a control. The control has a cor- 
responding cell in a worksheet. Different reports can use the same layout, 
and worksheets can hold data for different layouts. 

Reports, layouts, and worksheets are stored as ASCII text files. These 
files are processed by the RHYTHM SCP engine to create the actual 
mechanisms described by these text files. Changes to reports, layouts, 
and 'worksheets are achieved by changing the contents of these text files, 
and having the RHYTHM SCP engine process the files that have 
changed. 
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1 .2.2 Data Computation 

The following concepts describe the elements involved in computing 
data for reports: 

■ Worksheet - A worksheet consists of a table of cells serving as the 
computational element of the report mechanism. For the purpose of 
identifying the cells, columns are specified using a letter of the alpha- 
bet and rows are specified using a number beginning with 1. A single 
worksheet may be shared by multiple layouts. Worksheets are either 
normal, replicating, or functional as explained below. 

■ Cell - A cell contains an expression to display a result (the get expres- 
sion) and an expression to store a value (the set expression). The 
expression may compute a single value (can be stored in a normal cell) 
or multiple values (can be stored in a replicating cell). 

• normal - get expression and set expression must return a single 
atomic value (not a list) 

• functional (procedure) - get expression can return both atomic 
values and lists 

• replicating - get and set expressions always return lists, each ele- 
ment of which resides on a "layer" 

Every cell is referenced by a control in the layout that refers to the 
worksheet. 

■ Expression - An expression is a formula consisting of operators, func- 
tions, constants, variables, and parameters. Expressions are typed in 
the sense that there is a data type associated with each parameter, vari- 
able, constant, and function return value. Expressions may refer to 
internal models and their fields. 
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1.3 Directory Structure 



RHYTHM SCP searches directory paths to find worksheets, layouts, and 
reports, as well as system setup files, data import files, saved binary 
images, and so on. There are several environment variables that deter- 
mine the directory path RHYTHM SCP searches. These variables are set 
by corresponding RHYTHM SCP engine invocation options, such as: 

■ data - specifies the pathname to the directory that contains data import 
files for the RHYTHM SCP engine. 

■ reports - specifies the pathname to the subdirectories that contain all 
the available worksheets, reports, and layouts. 

■ system - specifies the pathname to the directory that contains system 
level data import files for the RHYTHM SCP engine. 

■ include - specifies other pathnames to be included in the search path. 

Every client that connects to the RHYTHM SCP engine will have associ- 
ated with it a particular directory path sequence to be searched to find the 
subset of worksheets, layouts, and reports associated with that client (the 
files in the system directory in part define this directory path sequence for 
every known client or user). RHYTHM SCP searches the directory path 
in sequence and uses the first occurrence of the file found. For example, 
if you have a pathname structure of alpha/beta/gamma, and a report ref- 
erences a layout that exists in gamma named layout Jile, then the file 
g ammo/lay out^file may be overridden by a file in alpha or in beta that is 
named layout J'ile. 
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1 ,4 Data Types 



RHYTHM SCP uses data types to give meaning to its data (e.g. is 123 the 
integer one-hundred twenty-three or is it the string containing the numer- 
als 1, 2, 3?). Types common to most programming languages are also 
available in OIL (e.g. logical, number). Application-specific types are 
also built-in (such as date_range) which are important for planning. A 
complete listing of all data types is provided in the RHYTHM SCP 
Model Reference Manual. 

Every type has an associated format which specifies how data elements 
of the type are to appear (e.g. how many decimal places of a floating 
point number are to be displayed). Multiple formats may be supported for 
the particular type based on the context and use of that type. For example, 
date might have the day first on import, but the month first on export. 
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section 2 Setup and Customization 



This section provides you with basic background information on OIL. By 
reading the material, you will have the basis for creating reports using 
various components of OIL. You will also have the basic knowledge for 
obtaining RHYTHM SCP planning data using OIL. 

2.1 OIL Overview 



OIL is the framework for the client interface and all customizations of 
RHYTHM SCP. As such, OIL is the primary implemented s tool. With 
OIL, a single framework is available for the following: 

■ to map data from external sources to RHYTHM SCP models 

■ to develop the necessary client interfaces (interactive or non-interac- 
tive) to perform the planning function on the server 

OIL is a strongly typed programming language. This implies the follow- 
ing attributes: 

■ All function invocations expect arguments of a definite type. 

m Results from expressions and function calls are of definite types. 

Utilities for conversion from one type to another are built into the lan- 
guage (both automatic and explicit). OIL optimizes the execution of rou- 
tines based on the context of the execution and the availability of data. 

OIL allows for the parameterization of interfaces. Interfaces can be tied 
to types of models (e.g. Site) instead of specific instances of models (e.g. 
Joe's Site). 

OIL also has limited built-in support for GUI utilities (widgets, icons, 
etc.). 
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2.1.1 Key Definitions 

Table 1 lists several key definitions that are important when learning 
OIL. 



Table 1: Key Definitions 







type 


Type is RHYTHM SCP's method of giving meaning to its data (e.g. is 123 the 
integer one -hundred twenty-three or is it the string containing the numerals 1,2, 
and 3?). Types common to most programming languages are also available in 
OIL fe 2 logical number) Each RHYTHM SfP mnrfel alcn rrmctitnt*»c a h, n /> 

V^'fe* ^gi^tu, nuiiiuL/iy. j-^civ_-i i ivii l j-j.Ai.vj. o v_-i 1UUUC1 dlaO COIlSLlLULeS ci type. 

Application specific types are also built-in, such as date_range, which are impor- 
tant for planning. Refer to the RHYTHM SCP Model Reference Manual for a 
description of all named types. 


formats 


Every named type has an associated format which specifies how data elements of 
the type are to appear (e.g. how many decimal places of a floating point number 
are to be displayed). Multiple formats can be supported for a particular type based 
on the context and use of the type (e.g. date might have the day first on import, 
but the month first on export). 


field 


Each RHYTHM SCP model has one or more fields that together implement the 
model's behavior. For example, the name field in the supply _chain model. Fields 
have types as well. For instance, name is a symbol. 


list 


A list is a collection of RHYTHM SCP data of the same type. Each list element 
has a position in the list, but list elements are not ordered unless explicitly sorted. 
Special OIL functions are available for operating on lists. 


expression 


An expression is a formula, in OIL syntax, consisting of one or more the follow- 
ing elements: 

• constants 

• parameters 

• variables and computes 

• functions 

• operators 

• model fields 

Expressions return a typed result. The software parses the formula to ensure its 
syntactic accuracy, compiles it into machine-executable code, then executes that 
code. 
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2.1.1.1 Expressions: Engine vs. Ul 

Engine and UI expressions are distinguished by where the expression is 
evaluated. FIGURE 1 illustrates this distinction: 



FIGURE 1 



Engine and Ut Expressions 




Parameter 
Expressions 



Engine 



Built-in & Model 
Functions 



Cell 
Expressions 



Action 




Control 


Expressions 




Expressions 



Built-in & GUI 
Functions 



UI 

"7 

Control Functions 



Any function that needs to access fields or information on the engine 
must be evaluated on the engine. 

2.1 .2 Reports - What are they? 

Reports are views of the planning data in context, given a user, a system 
environment, and input parameters. They include hardcopy printouts as 
well as GUI screens. Reports are created and managed with OIL. 

Reports are also models. Each User (also a model) can have its own set of 
custom reports (written for that implementation) and standard reports 
(written by i2). RHYTHM SCP defines environment variables that help 
determine how a given RHYTHM SCP client gets reports for its use. 
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2.2 Setup and Customization Overview 

The RHYTHM SCP server (scp_engine) is invoked from either a UNIX 
or Windows NT directory structure. The OIL client (scp_ui - batch or 
interactive, or scpjbatch) is invoked from a Windows NT directory 
structure. The system setup information for the application is also located 
in that same structure. 

2.2.1 System Setup 

The directory structure distributed with the system includes: 

■ include - the reference location (directory) for all input data to the 
engine. This directory is settable using the include option to the 
engine. Its default location is the location of the executables. 

■ custom - the default location for the license files (scp_engine.lic) 
and startup customization (scp_engine.opt and scp_ui.opt). 

■ system - the directory with model and user-specific customization 
settings. This directory is settable using the system option to the 
engine. Its default location is the system directory under the execut- 
ables directory. 

■ reports - the directory in which all reports information resides. Its 
default location is the reports directory under the executables direc- 
tory. This directory is settable using the reports option to the . 
engine. 

The system directory contains i2-maintained files that you should NOT 
be editing during an implementation. We do not worry about this in the 
training examples. However, you generally should create your own sys- 
tem directory and arrange to have it processed by RHYTHM SCP after 
the standard system directory has been processed if you need to custom- 
ize the system directory. 

Likewise, do NOT edit the contents of the i2-provided report subdirecto- 
ries. Make your own report subdirectory and arrange to have it override 
the standard report subdirectories. 
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FIGURE 2 shows the directory structure for scp__engine, scp_ui, and 
scpjbatch. 



FIGURE 2 



System Setup 



system 



i2-provided 
import files 



i2-provided 
data files 



include 



reports 
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Oil 
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scp . • 
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user-provided 
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custom 
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2.2.2 Environment Variables 

Environment variables are a form of communication between the engine 
and the operating system of the machine the engine is running on. They 
can pass information to and from different processes, such as the engine 
and the UI, or a UI from one user to a UI of another user. 

Information about the surrounding execution environment of the server 
and/or client is useful to have. RHYTHM SCP initializes environment 
variables that hold such information when the server or client is started. 
Examples of environment variables are: 

■ $I2_PID - the process id of the engine process 

■ $I2_APP - the application name 

■ $I2_HOME - the application directory (location of the executables) 

■ $I2_PORT - the port number currently being used 

■ $I2_REPORTS - the reports directory 

■ $I2_DATA - the data directory 

■ $I2_IMPORT - the default location of files for import 

■ $I2_EXPORT - the default location of files for export 

■ $I2_PRINT - the print command to be used for printing layouts and 



reports 



2-6 



Rhythm SCP Customization Manual 



March 27, 1998 © 1998 i2 Technologies, Inc. Proprietary Information 



Setup and Customization Setup and Customization Overview 



2.2.2.1 Environment Functions 

OIL functions for use with environment variables are getenv and setenv. 
The getenv function obtains the current setting of an environment vari- 
able. The setenv function sets the value of an environment variable. For- 
matting for these functions is shown below. 

The getenv function is formatted as shown below: 

getenv ("variable name") 

where getenv must be typed as displayed and substitutions must be made 
for variable name. This expression returns the current value of this vari- 
able. 

For example, 

getenv ( " $I2_IMPORT" ) 

returns the current value of $I2_IMPORT. 

The setenv function is formatted as shown below: 

setenv ("variable name", "value") 

where setenv must be typed as displayed and substitutions must be made 
for variable name and value. This expression sets the environment vari- 
able to the specified value. 

For example, 

setenv ( " $l2_EXPORT" , " /users /me" ) 

sets the value of $12 JEXPORT to the directory /users/me. 

You can give an environment variable any name. Environment variables 
set in one environment are not necessarily accessible in all environments. 
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2.2.2.2 System Directory Files 

Several key files reside in the system directory. These files exist prior to 
the receipt of RHYTHM SCP and usually only the .dat files require mod- 
ification. They include the following files: 

■ user, imp 

■ user.dat 

■ meta_model.imp 

■ meta_model.dat 

■ measure_model.imp 

■ measure_model.dat 

The user Amp and user, dat files contain user-specific customizations (e.g. 
user identities). meta_model.imp and meta_model.dat contain user- 
defined fields for extending models, measure Jbase Amp and 
measurejbase.dat contain recognized units of measure and their associ- 
ated conversions. 

2.2.3 Defining User Models in user.dat 

New users are defined in user.dat. If your user id is not in the global list 
of User Models at the server, then you can connect to the server, but only 
as the default New__User (if New_User is specified in user.dat). If 
New__User is not defined in user, dat, then anyone whose ID is not speci- 
fied in user.dat cannot connect to the server. It should be noted that the 
person who initiates the engine is defined as the super-user. Therefore, to 
use the scp_ui -user option, the user must be the person who started the 
engine. 



Additionally, a specification for the mix of user-specific custom and 
standard reports created in memory at startup, or incrementally, resides in 
user.dat for each User Model. Whether the mix is created at startup or 
incrementally is dependent upon the preload engine option. If the pre- 
load option is set to true, the application startup time is slow but the 
screens come up quickly. If the preload option is set to false, the applica- 
tion comes up faster but the initial display of each screen is slower. The 
benefit of setting preload to true is all reports are forced to be correct for 
the application to successfully start. Note: The default value of preload is 
false. 

Another Note: You can put the options that you will want most often in 
a separate text file, then load this file with the scp_engine option 
option _Jile my_opts. 
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The User Model has several fields that must be defined when creating a 
user. These include: 

■ name - corresponds to NT or UNIX user IDs 

■ report_directories - directory with reports specific to the user being 
defined 

■ organization - pre-specified user whose customizations are to be 
included 

■ include - pre-specified user whose customizations are to be included 
for a particular report directory {include is a field in the report direc- 
tory submodel of the User model) 

■ sequence - directories with smaller sequence numbers override those 
with larger sequence numbers {sequence is a field in the report direc- 
tory submodel of the User model) 

Each user can have its own set of report directories, although, user-spe- 
cific customizations should be stored in a separate directory. Definitions 
for these reports and all their components are incremental, thus, the last 
one read wins (hence the sequence property in the User Model specifica- 
tion). For instance, in the example shown in FIGURE 3, the main win- 
dow for user teacher is defined under the directory training and the main 
window for user student is defined under the directory scp. Both users are 
using the same supply _chain.wrk file under the directory scp. 



FIGURE 3 



Sequence Example 



reports 



scp 



main.rpt 



main. 



supply _chain.wrk| 



training | 



main.rpt 



main.lyt 



User Reports Directory Sequence 

teacher training 1000 

teacher scp 1200 

student scp 1200 
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FIGURE 4 and FIGURE 5 show sample user. imp and user.dat files. 



FIGURE 4 



user, imp Example 



import__text_f ile user 
{ file: "user.dat"; 

delimiter: ":"; 

worksheet ( ) { 

this = users; 

[Al : name - # ; ] 

[Bl : full_name = #;] 

[Cl: organization = # ; ] 

[Dl: report_directories . directory = #?".";] 
[El: report^directories . include = #;] 

[Fl: report„directories . sequence = make_type ( # , integer) ? 
report_directories . count; ] 

[Gl: current_data_directory = option ( "data" ) ? (option ( "spec" ) ?' 
import_record: Al Bl Cl Dl El Fl ; > 



) ; ] } 



FIGURE 5 



user.dat Example 



# name: full 

[unspecified] 
[unspecified] 
[unspecified] 
[unspecified] 
[unspecified] 
New_User : 
teacher: 
teacher : 
teacher : 
teacher : 
teacher : 
teacher : 



_name: organization: directory: user: sequence 



Default: 
Default: 
Default: 
Default : 
Default: 
New User: 
teacher : 
teacher : 
teacher : 
teacher : 
teacher : 
teacher: 



scp : : 
calendar: : 
rhythmlink: : 
oil: : 
basic : 

[unspecified] 
teacher : 
scp : 

calendar : 
rhythmlink : 
oil: 
basic : 



1000 
1400 
1600 
1800 
2000 

[unspecified] 

800 

1000 

1400 

1600 

1800 

2000 
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Using the user.dat file shown, all users receive a copy of the contents of 
New_User. The default NewJJser gets its directories from the [unspeci- 
fied] user. Note: If the user.dat is not completed properly, the client may 
be identified as New_User instead of the intended user (opening standard 
reports only, no customizations). 
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2.2.3.1 Defining Static Variables 

OIL provides support for static-type variables that allow values to be set 
and retained between opening, closing, and reopening RHYTHM SCP 
for such things as filter and user preference dialogs. This is achieved 
through the user-defined fields on the User Model. An example use 
might be for controlling the display of time information. By adding a log- 
ical field to the user model (e.g. timejnfd), you could control the time 
stamping of your output. 

if (user . time_inf o, echo ( "Starting export at" & 

now. string) ) ; 

For more information on the User Model, refer to the RHYTHM SCP 
Model Reference Manual. 

2.2.4 Defining Units of Measure in measure base. dat 

RHYTHM SCP supports defining domain-specific units of measure. 
Units of measure are defined in the measure Jbase.imp and 
measure_base.dat system files. New units of measure are defined in 
terms of the base units of measure. The base units of measure are: 

■ length 

■ mass 

■ current 

■ temperature 

■ time 

■ money 

■ pieces 

■ independent 

Conversion factors are specified between various units of measure. FIG- 
URE 6 and FIGURE 7 show sample measure Jbase.imp and 
measurejbase.dat files. 
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FIGURE 6 



measurejbase.imp Example 



import_text_f ile measure_base 
{ file: "measure_base.dat"; 
worksheet ( ) 

{ this = measure_bases; //this model uses special syntax 
measure = # ; ] //to indicate multi -dimensional UOM 
name = # ; ] 
full_name - # ; ] 
factor = #,-]} 
import_record: Al Bl Cl Dl ; } 

//It is assumed that the base unit for time is in seconds 



FIGURE 7 



measure_base.dat Example 



# measure 


name 


f ul l_name 


factor 










money- 


dol 


dollar 


1 


pieces 


Pt 


part 


1 


mass 


kg 


kilogram 


1 


mass 


g 


gram 


.001 kg 


mass 


mg 


milligram 


.001 g 


length 


m 


meter 


1 


length 


cm 


centimeter 


0.01 m 


length [3] 


1 


liter 


1 


length [3] 


ml 


milliliter 


.001 1 


length*mass * t ime { - 2 ] 


N 


Newton 


1 


length [2] *mass* time [ -2 ] 


J 


Joule 


1 


time 


sec 


second 


1 


time 


min 


minute 


60 sec 
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2.2.5 Defining User-Defined Fields in meta model.dat 

Most models are extendable with user-defined fields. User-defined fields 
are specified in metajnodel.dat through the Model_Type Model. Every 
user-defined field is of a specific type. Type-specific formats are used for 
display and input. FIGURE 8 and FIGURE 9 show sample 
meta _model Amp and meta_model,dat files. 



FIGURE 8 meta„modelJmp Example 




FIGURE 9 meta_model.dat Example 



# Model; Value_Type; Field_Name; Description 

Buffer ; Symbol ; short_name ; 

Item; Symbol; short_name; 



The metajnodel.dat defines a field short _name for the Buffer and Item 
models. Such fields are really understood only at the client, but the soft- 
ware can perform general calculations with them by using them in OIL 
expressions. 
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2.2.6 Reports Directory 

The reports directory contains all report information. Its location defaults 
to the reports directory under the executables directory. However, its 
location is settable using the reports option. 

All standard reports and utilities reside in the following subdirectories 
under the reports directory: 

■ basic - default formats, styles, and reports 

■ oil - reports for the OIL interactive editors 

■ rhythmlink - reports for RhythmLink 

■ calendar - reports for the Calendar Editors 

■ scp - standard SCP reports 

All custom reports reside in other subdirectories under the reports direc- 
tory. 

There are advantages and disadvantages to having the reports directory. 
One advantage is incremental changes can be made for a specific user 
without affecting the customization for others. One disadvantage is the 
dependencies between reports and their components can become compli- 
cated and need to be well documented. 

2.2.7 Using .opt Files 

Options and flags are generally set to the scp_engine and scpjui in-line. 
These options and flags can be placed in .opt files rather than specifying 
them in-line. When invoked, scp_engine by default looks for a file called 
scpjengine.opt in the same directory, and scp_ui looks for a file called 
scpjui. opt. 

The startup: option for scp_engine specifies an OIL expression to be run 
at startup. Since certain OIL functions can specify the use of other files, 
any amount of work can be accomplished during startup, including 
importing orders, forecasts, planning and running strategies, etc. 
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2.2.8 Using .in Files 

.in files are OIL script files which are interpreted and executed by 
scp_engine. They contain a series of OIL expressions and OIL functions 
and are usually invoked by a do _Jile function (i.e. 

do_f ile ( "my_commands . in" ) ). 

The before _import. in , after_importin, before _export.in, and 
after jzxport.in files are automatically invoked by the import and export 
functions. If the first parameter of the import or export function is a 
directory and that directory contains a before JimporLin, etc., file, the 
contents of this file are evaluated before or after the other files in the 
directory are imported or exported. 
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2.3 More Basics 







As mentioned previously, OIL is a strongly typed language. It consists of 
numerous models that represent the many elements of a supply chain. 
Each model has submodels, fields, extensions, and functions, and each 
submodel has its own fields, extensions, and functions. 



2.3.1 OIL Models 

A model is a data structure in OIL that: 

■ represents an entity in the supply chain world 

■ has fields that can either produce values or execute commands 

■ has at least one field used for identification purposes, usually called a 
key field 

■ has another model that is the designated owner 

Models are the building blocks for the various entities in the supply 
chain. They contain all the necessary information that characterizes the 
entity being modeled. Models also form the framework within which the 
behavior of individual entities can be extended for specific requirements. 

Every model is also a type (Model_Type). Each model has a key field 
that allows RHYTHM SCP to distinguish individual instances from one 
another (e.g. used by the find function). Each model has submodels from 
which the parent model can be accessed using the owner field under the 
submodel. For example, consider the following expressions: 

load . owner 

operation . owner 

where load and operation are the submodels. The first expression returns 
Operation as the parent model. The second expression returns Site as the 
parent model. 



© 1998 i2 Technologies, Inc. Proprietary Information 



March 27, 1998 



Rhythm SCP Customization Manual 2-1 7 





More Basics 



Setup and Customization 



FIGURE 10 shows the relationship between the Supply _Chain, Site, 
Seller, and Plan models in a supply chain. (The Site model is expanded in 
this example.) 



FIGURE 10 



Models and Submodels 



Buffer // of LINK Site 



Supply _Chaih ; 



Site 



Seller 



Item// of LINK Site 



Plan 



Operation // of LINK Sii e I Resource // of LINK 



Skill // of LINK Site 



Load 



Flow 



2.3.2 Model Fields 

The following types of fields exist: 

■ standard 

■ values 

■ commands 

■ extension 

■ user-defined 

■ key 

■ owner 



Fields correspond to data elements of specific types within a model. 
Accessing a field within a model is equivalent to invoking & function with 
the same name as the field that has the model as an argument. For exam- 
ple, the following expressions are equivalent: 



Site . name 



name (Site) 



where Site is the model and name is the field. 
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FIGURE 1 1 displays the fields of the Supply _Chain and Site models. 



FIGURE 11 



Supply_Chain and Site Model Hierarchy 



Supply_Chain 
I 



Site 



— Name 
— Description 
— Category 
— Organization 
— Members 
— Member^of 
— Role 

— Margtn_Target 
— Oelivery_Name 
— Delivery_Contact 
— Delivery_Phone 
— Delivery_Fax 
— Delivery_Address 
— De1ivery_City 
— Delivery_State 
— Delivery_Country 
— Delivery Postal Code 
— BillingJName 
— Bi!ling_Contact 
— Billing_Phone 
— Billing_Fax 
— Billing, Address 
— Billing City 
— Billing~State 
— Billing_Country 
— eillina PostaLCode 
— Taxjdentification 
— Site_Plan 
* — Owner 



Buffer //of LINK Site 



Seller. 



Plan 



Name 
Description 



4: 



Item //of LINK & 
SUPPLIER Site 



—Name 

— Item 

— Description 

—Location 

— Category 

— Owner 

— Buffer_Plan 

— Problem. Detectors 

— Level 

— AII_Producing_Ope rations 
— All Consuming_Ope rations 
— Unit 

1 — Al LSupptyi ng_Ope ratoi ns 



— Name 

— Delivery (unspecified) 
—Description 
" itegory 
iraitfngllD 
amily 
-^Children 
— Artificial 
ots_Tracked 

^ufferVlans 

Unit 
*— Owner 



I 



Operation // of LINK 
Site 
I 



Resource //of LINK Site 



—Name 
— Description 
—Category 
— Jnterruptible 
— Loads 
— Flows 

—Consume. Flows 
— Produce_Flows 
— AII_Consume_Flows 
— AII_Produce_Flows 
— AILFIows 
—Sub_Ope rations 
— Super_Operations 
— Problem_Detectors 
— Planning_Buffers 
— Planning_Resources 
— Operation_Plans 
—Unit 

— ReIease_Fence 
— Release_Soon_Fence 
— Release_Name_Expression 
— Next Release_Number 
— Release_Number 
1 — Owner 



Flow 



-Name 

-Buffer 

-Phantom 

-Produced 

■Owner 



Skill //of LINK Site 



— Name 

—Description 

—Skills 

— Category 

— Location 

— Probl em_ Detectors 

— Resource_Plan 

—Owner 



— Name 

— Description 

— Resources 

— Loading_Operaions 

— Loading_Buffers 

— Owner 



Load 



—Name 
— Resource 
—Skill 

—Start-Setup 
— End_Setup 
— Start_Location 
— En d_ Location 
— Owner 
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Fields describe model-specific information (e.g. name field of the Site 
model). Each field is a function in OIL. They can be defined to take more 
than one argument. If a field is not defined as export_only, it may have a 
built-in function for setting its value (named as "set_xxx"). 

For example, the expression 

buf f er_plan . on_hand ( ) 

returns the quantity on hand at the buffer. To set that quantity, write the 
following expression: 

buf f er_plan . set_on_hand ( 10 ) 

Many fields have default values. The exception is a model's key field 
which does not have a default value. The value [unspecified] (built-in 
identifier) is typically used for default values whose type is a model. 

Several fields name extensions. These extensions are used to customize 
the behavior of the particular model. The extensions identify which sub- 
models and fields are active in a model. For example, Site.role = "LINK" 
declares the role of this submodel Site as a link in the supply chain. As 
such, the site can be modeled in detail and is used to transfer items 
between buffers, and to place requests and provide promises to other 



Typically, the value of an extension selector such as "LINK" affects 
whether certain fields of a model are active. The exists( ) function tests 
whether or not a field is active. For example, the expression 
exists (operation) returns "TRUE" if an operation field exists and 
"FALSE" if an operation field does not exist. When a field is not active, 
invoking it causes the function nonexistent to initiate, which has the prac- 
tical effect of a null result. This is not an error. 



Sites. 
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2.3.2.1 Model Extensions 

RHYTHM SCP uses extensions in conjunction with fields to customize 
the behavior of a model. The extension, in effect, adds fields to the 
model. Refer to the RHYTHM SCP Model Reference Manual for more 
information on extensions. 

FIGURE 12 shows the extensions for certain fields within the Site model. 



FIGURE 12 



Extensions of the Site Model 
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SUPPLIER 
CUSTOMER 

— Name 
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INFINITE_USE 
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2.3.3 Model Functions 

Functions operate on one or many arguments to return a result of a speci- 
fied type. They can be nested to as many levels as there are fields defined 
in a model or submodel. For example, the following expressions A and B 
are functionally equivalent. 

start ( 

horizon ( 
f ind( 



A function that expects multiple arguments can also be written as a field 
or function of the first argument. For instance, consider the following 
expressions: 

problems (Site_Plan, Problem_Category) 
Si te_Plan . problems ( Problem_Category ) 

where the first expression is a function using problems, which is a field of 
the Site_Plan model, as written in the second expression. 



plans ( 

find ( supply_chains , 
"My Supply Chain") 

) , "Actual Plan") 



Expression A 



supply__chains . find ( "My Supply Chain" ) 
.plans. find ("Actual Plan") 
. horizon 
. start 



Expression B 
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2.3.3.1 Using the nonexistent Function 



Most functions do nothing at all when encountering nonexistent. For 
example, the expression f (e) returns nothing if E encounters nonexist- 
ent. The only exceptions are these OIL functions and operators: 

■ exists - this function returns FALSE if the second parameter is nonex- 
istent; otherwise, it returns TRUE 

■ = = - these operators return FALSE if one or both parameters are non- 
existent 

■ /= - these operators return TRUE if one or both parameters are nonex- 
istent 

■ contains - this function returns FALSE if its second parameter is non- 
existent 

■ find_or_nonexistent - this function returns nonexistent when no 
matches are found 

■ found - this function returns FALSE if its second parameter is nonex- 



■ ? - this operator returns the first parameter if it does not abort out with 
nonexistent; otherwise, it returns the third parameter 

The expression exists (E) returns "FALSE" if E encounters nonexist- 
ent, otherwise, it returns "TRUE". The expression e ? x returns E if it 
does not encounter nonexistent, otherwise, it returns X. 

The following is an example expression using the nonexistent function: 

[Gl request = i f ( deliv_op . exists , 
deliv_op.motive_request, nonexistent:) ;] 

Note: This expression is redundant and can be simplified to be more effi- 
cient: 

[Gl request = deliv_op . motive_reques t ? ] 



istent 
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The nonexistent function is the OIL equivalent of "undefined". You can 
give undefined things this value so that you can test for it with other func- 
tions. 

You can create something with the value nonexistent using the 
make_type function: 

variable old_request = make^type (nonexistent , Request) ; 

if (old_request . exists , echo ( "There is already a request")/ 
set_variable { old_request , new_request) ) 



2.3.3.2 Symbolic Constants vs. Zero-Parameter OIL Functions 

Zero -parameter functions require no parameters and do not require 
quotes in their syntax, nonexistent is actually an OIL function that takes 
no parameters. Other common zero-parameter functions include: 

■ now - returns current date and time 

■ rand - returns an evenly distributed random number between 0 and 1 

■ report - returns the current report 

■ user - returns the user for the client, or nonexistent 

■ close - closes the current report window 

In contrast, symbolic constants (such as the various model extension 
names) are predefined values within OIL that have specific meanings. 
They are not functions and need to be placed in quotes in OIL expres- 
sions (e.g. my_site.role = = "LINK"). However, it is an error to quote 
zero-parameter functions (e.g. nonexistent). 
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2.3.4 Types and Conversions 

Values have types that are dependent on the OIL expressions. For exam- 
ple, consider the following expressions: 

plans . first .horizon 
plans . first . horizon . start 



The first expression returns a type of DateJRange. The second expres- 
sion returns a type of Date. OIL consists of the following types, grouped 
in the table below by category: 



Category 


Types 


Numeric 


Integer, Number, Percentage 


String Symbol 


ID, Logical, Pathname, String, Symbol 


Date Time 


Date, Date„Range, Horizon_Date, Restriction 


Quantity Measure 


Measure, Measure_Unit, Money, Quantity, Quantity _Range, 
Time 


Special 


Cell_State, Change_Category, Event, Expression, Predicate, Pri- 
ority, Reference, Type, Typed_Value, Void 


List 


Homogenous, Keyed, Bucketed, Recursed 



Refer to the RHYTHM SCP Model Reference Manual for detailed defini- 
tions of all the types. 



Any conversion required from one type to another is managed intelli- 
gently (e.g. String to most other types is converted automatically). Note: 
Any type to String is not automatic. Use the string ( ) function to convert 
a Symbol, etc. to String. 

The following expression shows an example of types: 

operation . flows . first . quanti ty_per = "23" 

quantity _per is of type Quantity but "23" is of type String. Although this 
expression will work without explicit type conversions, a type conversion 
function can be used to force the conversion. The string ( ) function is an 
example of a type conversion function. Refer to the RHYTHM SCP 
Model Reference Manual for definitions of all the type conversion func- 
tions. 
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2.4 Engine and Ul Options 

RHYTHM SCP is designed to be customizable. Customization may be 
implemented through one of the following mechanisms: 

■ engine - Rhythm SCP options supplied at the engine level (See FIG- 
URE 13) 

■ Ul - Rhythm SCP user interface (Ul) options supplied at the client 
level (See FIGURE 13) 

■ reports, layouts, worksheets, styles, formats 

■ data files 

RHYTHM SCP option (.opt) files allow for customization of such items 
as the following: 

■ behavior of the engine 

■ behavior of the UIs 



FIGURE 13 



Engine/Client Option Architecture 
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2.4.1 Overview 

This section begins with a brief overview of the option mechanisms. It 
then presents a discussion of topics which apply to both the engine and 
Ul and to RHYTHM SCP options: 

■ Naming Option Files 

■ Specifying Options 

The remaining sections discuss the following topics: 

■ All available RHYTHM SCP engine options and Ul options are listed 
and described 

■ Environment variables 

2.4.1.1 Engine 

The engine program runs with a specific set of options. The option values 
with which the program runs may be modified by supplying: 

■ RHYTHM SCP option/value pairs on the RHYTHM SCP engine com- 
mand line 

■ RHYTHM SCP option/value pairs in .opt files 

2.4.1.2 Ul 

The client program runs with its own specific set of Ul options. The 
option values with which the program runs may be modified by supply- 
ing: 

■ RHYTHM SCP option/value pairs on the RHYTHM SCP client com- 
mand line 

■ RHYTHM SCP option/value pairs in .opt files 

2.4.2 Naming Option Files 

The RHYTHM SCP application options can be specified for either all 
RHYTHM SCP applications or specific RHYTHM SCP applications, and 
can be specified for an entire customer site or for particular users. 
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2.4.2.1 Naming Rules 

The following rules govern the names that option files should be given: 

■ Options for RHYTHM SCP applications have the suffix .opt. 

m Options that apply to all RHYTHM SCP applications should be speci- 
fied in files named il.opt. 

m Options for the engine level (the file containing RHYTHM SCP appli- 
cation options for the engine level) should be named scp_engine.opt. 

m Options for the UI level (the file containing RHYTHM SCP options 
for the UI level) should be named scpjui.opt. 

■ Option files which are Site-wide should be placed in the custom subdi- 
rectory of the RHYTHM SCP directory. For example, if RHYTHM 
SCP is installed in the directory /usrAocal/Rhythm, then the site-wide 
options would be in the directory /usrAocal/Rhythm/custom. 

m Option files which are User-specific should appear in the user's home 
directory. 

■ Option files can have any name you wish as long as you use the 
option _file option to name them 

2.4.2.2 Search Rules 

The following rules explain the directories that are searched for option 
files. To obtain the values for options, RHYTHM SCP searches a 
sequence of directories (called a search path) in a specific order. The 
value of an option found in a file in one directory overrides, or resets, the 
value of the same option found in a file in any of the directories in lower 
priority in the search path. This search sequence allows a user to override 
the site-wide options, which can override the i2 Technologies-supplied 
options: 

■ Command line options - highest level of priority. Any options speci- 
fied on the command line call of a RHYTHM SCP application over- 
ride any of the options specified in the files described below. 

■ Standard RHYTHM SCP settings - i2 Technologies-supplied defaults. 

■ At the same level (user-specific, site-wide, standard), application spe- 
cific settings will override all RHYTHM SCP settings. 
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2.4.2.3 Default List of Option Files 

The default list of option files to read comes from the app_name_options 
environment variable. If this variable does not exist, then RHYTHM SCP 
searches each of the option files shown in Table 2 for the RHYTHM SCP 
options, if they exist. The following conventions are used: 

■ <app_dir> indicates the pathname to the executable file which runs 
the RHYTHM SCP program. 

■ <app_name> indicates the RHYTHM SCP application program 
(which may be overridden with the name command line option) that is 
being run. For example, scp__engine. 

m $HOME indicates the user's home directory. 

The table is ordered from highest (most specific; current directory) to 
lowest (most general; home directory) level of override priority. Com- 
mand line options override option file values. 



Table 2: Search Rules for RHYTHM SCP Options 



Rule 


File 


Level 


Scope 


9 


command line options 


user specific 


all RHYTHM SCP 


8 


<app_name> . opt 


site-wide 


application specific 


7 


i2.opt 


site-wide 


all RHYTHM SCP 


6 


<app_directory>/<app_jiame>.opt 


standard 

RHYTHM 

SCP 


application specific 


5 


<app__directory>/i2. opt 


standard 

RHYTHM 

SCP 


all RHYTHM SCP; 
should not be altered by 
customers 


4 


<app_directory>/custom/ 
<app_name>. opt 


site-wide 


application specific; 

may be altered by customers 


3 


<app_directory>/custom/\2.opt 


site- wide 


all RHYTHM SCP; 

may be altered by customers 


2 


$HOME/<app_name>.opt 


user specific 


application specific 


1 


$HOME/i2.opt 


user specific 


all RHYTHM SCP 
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2.4.3 Specifying Options 

Each option has a name and a data type. The data type is a descriptor for 
how the value of the option is to be entered on the command line or in the 
option file. The available data types are as follows: 

■ Boolean- a Boolean flag which has a value of either TRUE or FALSE. 

As a command line option, this type may be implemented by preceding the option 
with an optional plus or minus sign to indicate its value: 

+option set it to a value of TRUE 

-option set it to a value of FALSE 

option toggle the TRUE/FALSE value of the option 

It may also be implemented by preceding the option with a minus sign, and entering 
an explicit TRUE or FALSE (case insensitive) following the option name. 

Examples: 

appname +turn_me_on -turn_me_off toggle^me 

appname -turn_mej3n TRUE -turn_me_off FALSE 

m Float - the option represents a floating point number. 

■ Function - Looks like some other data type to the user, usually String, 
m Integer - the option represents an integer number. 

■ String - the option represents a character string. 

2.4.3.1 Command Line Option 

Option values may be specified on the command line. For example, 

scp__engine port 6162 & 

where 

scp_engine is the name of the program 

port is an integer option set to integer 6162 

& run program in the background 

If an option on the command line is not recognized, a help message is 
displayed, and the program terminates. 
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2.4.3.2 Option File Format 

The option (.opt) file format is modeled after XI 1 resource files, except 
that no wild-carding is performed. There is one line per option. Each line 
has the option name followed by a colon, then by a value. For Booleans, 
the value will be either TRUE or FALSE: 



! Comments begin with ! 

! The following line initializes the open option with the string 
! my_customer . i2 
open: my_cus tomer . i2 

! Upon engine startup, evaluate an OIL expression that plans to 
! satisfy all requests in all the models in the engine 
startup: 

supply_chains . f or_each (# .plans . f or_each (# . site_plans . for_each 
( # . planet o_sati s f y_al l_r eques t s ) ) ) 



name : value 



A space may follow the colon but not precede it. 



An example option file: 
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2.4.4 Available Options 

To view a list of the available RHYTHM SCP options which can be used 
as command line options, the executable should be run with the help 
option. To view engine or UI options, that users implement frequently, 
e.g. data, host, open, port: 



To view all UI options (UI options that users implement frequently, and 
options that are used to customize RHYTHM SCP, e.g. default Jormat, 
default _style)\ 



If an option on the command line is not recognized, a help message is 
displayed, and the program terminates. 

Note: At the time of printing this manual, due to a limitation in Windows 
NT, this capability does not work correctly for scp_engine and scp_ui 
execu tables. It does work correctly in Unix. 



scp_engine help 
sepjui help 
sepjbatch help 



scp_engine help all 
scp_ui help all 

sepjbatch help all 



To view detailed help on one particular option: 



scp_engine help <option> 
scp_ui help <option> 

sepjbatch help <option> 
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2.4.4.1 Standard Options 

Table 3 lists the engine and UI options that users implement frequently 
and that are common to both the engine and UI executables (scp_engine 
help, scpjui help and scpjbatch help). Table 4 lists the options that users 
implement frequently with the engine executable but that do not apply to 
the UI executable (scp_engine help only). Table 5 lists the options that 
users implement frequently with the UI executable but that do not apply 
to the engine executable (scp_ui help and scpjbatch help only). 



Table 3: Standard Options - Engine and UI 





: 4$ '. 


/^VXy^^--: V;,, ; i|^.,; '. 




deadman_timer 


U-Integer 


FALSE 


Kill engine when idle more than the indicated number 
of MINUTES. Zero (default) disables this option. 


debug 


Boolean 


FAT SF 


iviuaL uc scl u j ii\ur> ^ l ) lo eiiduie uiL ueougger 
breakpoints. This option is automatically set to TRUE 
when it encounters the first enabled breakpoint. 


def ault_metric s_percentage 


U -integer 


OA 


Only report users of the top X% of memory. 


help 


Function 




Print documentation for all options. Specifies all of the 
known option names, types, and values. 


host 


String 


"localhost" 


Default host name. If empty, use the current machine 
name. 


iden ti fi er_compatibil ity 


Boolean 


FALSE 


If TRUE, identifiers will be converted to strings (or 
symbols) with a warning. 


ignore_strings 


String 




Ignore strings from this file. 


include 


Function 


(NULL) 


Adds a directory to the list used for opening data files. 
If a relative pathname is given for a data file or direc- 
tory, the include path is searched to find it. The default 
is "." (the current directory), include may be specified 
multiple times. Each time, the specified path is pre- 
pended to the previous path, path may be a single 
directory, or a list of directories delimited by one or 
more " \t,:" (Note: report/layout/worksheet/style/for- 
mat files use the search path defined by the user data- 
base). 


java„src 


Boolean 


FALSE 


Parse java source, generating strings. 


language 


Function 


(NULL) 


Default language. 
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Table 3: Standard Options - Engine and UI 











log_fiie 


String 


log_file 


This command line option saves output to the named 

file in addition to writing to stdout (or stderr). This 

option works with any executable (scp_engine, scp_ui, 

rl_engine, modelgen, etc.). Output is flushed to the file 

after every line. 

The format for this option is: 

scp_engme port 0 log_nle foo 


max_clients 


Integer 


5 


Maximum number of clients allowed to connect to this 
engine. 


max_errors 


Integer 


10 


File reading error messages will be printed at most 
max_errors times per file. 


max_records 


U- Integer 


1000 


Maximum number of records to be viewed per table by 
the GUI. 


mprof 


Function 


0 


Report profile data when total allocation changes by N 
megabytes. 


mprofjog 


Function 


./memory. mprof 


Record memory profiling file in the specified log file. 


mprof_metrics 


Function 


0 


Report metrics every X megabytes. 


open 


String 


a*? 


Restore data from this directory. To prevent importing 
on top of a restored dataset, make sure that the follow- 
ing entry does not exist in the i2.opt or scp_engine.opt 
files: 

data: <directory> 
Select the Import and Save (Save As) options in the 
File menu of the main window to restore and save the 
model. 
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Table 3: Standard Options - Engine and UI 







us,. r ., ■ 

ueiauit 




option 


Boolean 


FALSE 


If set to TRUE, report where options originate. A trace 
of which options come from what option files is 
printed. 


Example of engine options reported when option is TRUE: 




Reading options from Jil.opt 

Option include = tests . /rhythm/data 
Reading options from ./scp_engine. opt 

Option open = electronix.i2 
■ Option startup - 

supply _chainsf or _each(#. plans jor_each( #. site _plans.for_each( #.plan_to_satisfy_all_requests ))) 
Option command_execute = true 

Option print_usage = mean sum realtime, mean sum memory, mean run pause 
Option recurse_depth = 100 

Restoring scp_engine version 3_07 A on zip started by john at 03/14/98 15:47:13 

supply ^chains for _each( #. plans. J r or _each( #. site _plans.for_each{ #,plan_to_satisfy_all_requests ))) 

Handling requests from port 27111 


Example of UI options reported when option is TRUE: 




Reading options from JH.opt 

Option include = tests . /rhythm/data 

Reading options from Jscpjui.opt 

Option splash = false 
Option user = electronic 






option_file 


Function 


(NULL) 


Read an options file. 


port 


Integer 


27111 


TCP Port of engine. 


preload 


Boolean 


FALSE 


If set to TRUE, preload all reports, layouts, work- 
sheets, styles, and formats. 

If set to FALSE (default), report Files are loaded incre- 
mentally, user <name> then causes scpjui to use the 
<name> user. 

In effect, the following entries are equivalent: 
scp_engine -preload user <name>&; scpjui 
scpjengine -preload&; scpjui user <name> 
The following entries are also equivalent: 
scp_engine -preload user <name> 
scp_engine -preload newjuser <name> 
If a value of FALSE is used on the engine, then the cli- 
ent comes up faster because it loads the reports only 
when necessary. 


show_progress 


Boolean 


TRUE 


If set to TRUE, display progress messages. 
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startup_hook 


String 


"(NULL)" 


Shell command to run after connecting to client or 
engine. 


tdir 


String 




Directory where the engine looks for translations. 


term_width 


Integer 


80 


Terminal width in characters. Used to widen the dis- 
play output when the help feature documentation is 
truncated. A value of 132 is usually sufficient. 


version 


Function 


(NULL) 


Display the version number and date without loading 
data files. Using port 0 provides the same results: 

scp_engine version 3_07 A of 04/0 1/98 
scpjui version 3JD7 A of 04/01/98 


which_server 


Boolean 


TRUE 


Detects another server on the same port. Set to FALSE 
to avoid Rhythm2 server crashes when a Rhythm3 
server is using the same TCP port as a Rhythm2 server. 
Set to TRUE to enable the feature of reporting which 
scp_engine is using the requested TCP port. Default is 
TRUE because few users will be using both Rhythm2 
and Rhythm3 at the same time, and because you would 
have to work at it to use the same port. 
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Table 4 lists the options that users implement frequently with the engine 
executable but that do not apply to the UI executable (scp_engine help 
only). 



Table 4: Standard Options - Engine Only 





■llilli 




v:v vr.:r,^ - : = : .. 5 ^IJeiimtlOIl^-^-^ •• ■ '< ; ->..-:'' : \< -v-- 


cal__plan_period 


Function 


(NULL) 


Specifies the default plan period for Calendar_Plan. 


data 


String 


"(NULL)" 


Import data from this directory. To prevent importing 
on top of a restored dataset, make sure that the follow- 
ing entry does not exist in the i2.opt or scpjengine.opl 
files: 

data: <directory> 
Select Import and Save {Save As) options in File menu 
of the main window to restore and save the model. 


default_temp_table_threshold 


Integer 


2147483647 


Specifies the maximum number of temp table records to 
keep in memory. 


dts 


Integer 


FALSE 


If set to TRUE, save all data and options to a directory 
named with the dts number. 


dts_old 


Integer 


0 


Save all data and options to /tips/data/dts/9999 (where 
9999 is the dts number). 
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flow_policy„threshold 


Float 


le-05 


Buffer roundoff threshold value. 

Tells Buffers how close two numbers have to be to con- 
sider them equal (cannot depend on perfect equality 
because of the limitations of computers in dealing with 
real numbers). 

For example, if a Buffer requests a supplying operation 
for 10 units, and it comes back with 9.99 units, that is 
probably OK. But if it comes back with 9.5 units, that is 
probably not. By using a flow _policy _threshold greater 
than 0.01, but less than 0.5, Buffer code will interpret 
those numbers correctly. 

The default flow_policy_threshold is 0.00001. It 
demands a close match by default, so as not to throw 
away real material thinking it is roundoff. 
Math processors only give a fixed range of precision. 
This means that the biggest Flow_Plan in or out of a 
Buffer needs to be no more than 160,000,000 times as 
large as the flow ^policy jthreshold. (That is not some- 
thing that can be controlled. It is a feature of the hard- 
ware.) With the default threshold, problems may begin 
to occur when dealing with Flow„Plans bigger than 
1,600 (= 160,000,000 * 0.00001) units. 
Those problems can show up in a variety of ways, but 
the most common is a sudden explosion of tiny 

wjjh auuii * laiis, C-UV-il JUoL UalK^ly aUUVC L11C 

flow_policy_threshold. 

If you need to deal with Operational ans bigger than 
1,600 units, and you do not need to accurately represent 
quantities as small as 0.00001, then you will probably 
want to set a higher flow jpolicy threshold, but keep in 
mind the following rules: 

• Never set it higher than 1/4 the size of the smallest 
units you want to represent. For example, if the smallest 
units in your factory are a half of something, never set it 
above 0.125. 

• Never set it to a negative number. This causes the 
engine to run indefinitely. 

• Never set it greater than 1 .0. 


interaction_coefficient_destroyed_factor 


Float 


1 


The interaction factor of destroyed problems. 
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intcraction_coefficients 


Boolean 


TRUE 


Activates interaction coefficients Whpn FAT SF fnrrps 
all coefficients to be 1.0. 

Interaction coefficient is the measure of the likely prop- 
agation of problems from a FLO object (based on past 
experience). Interaction coefficients are learned as 
problem solving progresses. They reside on FLO 

nhlPPts flTiH mPfisiiTP nast PYnprlpnnp with rpcnlviticr 
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problems on that object. If past resolutions have caused 
many problems (or dramatically changed the goal func- 
tion), then this is reflected in the interaction coefficient. 
Each time a problem is resolved on a FLO object, a new 
interaction coefficient term is generated which mea- 
sures the effect of that resolution. The actual interaction 
coefficient for the object is a weighted average of the 
terms. 


license 


String 


"(NULL)" 


Enter license key from the command line. 


mt 


U Integer 


4 


Maximum number of commands that can be run in par- 
allel. 


mt stack size 

1111 uLUwiV iJlijV 




10 MB 




new_eff_alt_behavior 


Boolean 


FALSE 


When TRUE, use alternate Effective_Calendar opera- 
tions only when the 

USE„EFFECTIVE_ALTERNATES change category is 
specified. 


ofl_bucketize 


Boolean 


FALSE 


Makes OFL problems bucketized. Note: Problems can 
extend more than a bucket in length. If set to TRUE, 
OFL problems will be no longer than one bucket in 
length. 


ohc_split 


Boolean 


TRUE 


Causes the move_in and move_out OHC resolves to 
split if necessary. Also splits operation plans (if neces- 
sary) while resolving overloads in OHC and FLC buff- 
ers using alternate_operations. 


prob_selection„age_usage 


Float 


0 


When nonzero, young problem ages are preferred when 
selecting problems. When you run a strategy, problems 
are created. These problems are dated (using the Date 
Activated field). When you make changes to the plan, 
new problems are created. When you run the strategy 
again, you can use prob _s election age __usage to spec- 
ify that the strategy looks only at the newest problems, 
and ignores older ones. 


random_seed 


Boolean 


FALSE 


Causes SDP to reset the seed to a random value. 
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rap_threshold 


Boat 


0.0001 


Request and promise quantity problem detection thresh- 
old. 


reports 


String 


"$I2_REPORTS" 


All relative User report_directories pathnames are rela- 
tive to this path. 


resource_ignore_tabu 


Boolean 


FALSE 


When TRUE, resource resolvers ignore tabu restric- 
tions. 


save32 


Boolean 


FALSE 


Save 64-bit binary files in 32-bit format. 


spec 


String 


"(NULL)" 


Read import files from this directory. 


startup 


String 


"(NULL)" 


Evaluate a worksheet expression at startup. 


startnn file 


String 


"(NULL)" 


Evaluate this expression file at startup. 


system 


String 


"(NULL)" 


System data directory. 

Import data from specified directory. The default is the 
system directory which contains data shipped with the 
system. Any or all of these Files can be edited and 
placed in another directory (see data). The files include: 

measurejbase.dat - Defines default units of measure. 

meta_modeLdat - Defines user defined data fields. 

user.dat ~ Defines the user model, which tells 

scp_engine where to load report files. 
See separate section titled Environment Variables for 
more details. 


tabu_enforce 


Float 


0.5 


Adjusts tabu enforcement. 1 = always enforce. 0 = 
never enforce. 0.5 = default. 


tabu_restrictions 


Boolean 


TRUE 


Specifies whether SDP tabu restrictions are active. 
Note: If changed after startup, old restrictions are not 
flushed. 


user 


String 


"(NULL)" 


Preload all of the reports / layouts / worksheets / styles / 
formats for this user before servicing GUI requests. 
This is a name in the user name field in the user.dat file 
(User model). 


user_data 


String 


"(NULL)" 


User import directory. 


user_spec 


String 


"(NULL)" 


Read user import files from this directory. 
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Table 5 lists the options that users implement frequently with the UI exe- 
cutable but that do not apply to the engine executable {scpjui help and 
scpjbatch help only). 



Table 5: Standard Options - UI Only 
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allow window growth 


Boolean 


FALSE 


If set to TRUE, report windows are always allowed to 
grow to fit currently visible layouts. 


batch 


String 


"(NULL)" 


An expression to execute INSTEAD OF displaying any 
windows: 

Example 1: 

scpjui batch "echo(3+5)" 

Example 2: 

To save the current plan to a file with a filename 
containing the date and time that the file is saved 
(now): 

scpjbatch batch 'save( "scp_ " & now & ". i2 ") T 

The expression could be placed in a file, c.g.file.in, and 
executed either as a parameter to the engine: 
scp_engine startup 'do_file("file.in"y 

or as a batch client: 

scpjui batch l doJile{"file.in"y 

All batch commands start off executing on the engine. 
Formerly, they executed on the GUI (unless the GUI 
just sent them right back to the engine). This saves one 
or two round trips between the server and client. 

Batch commands do not load the current user's reports 
unless the load jail option is in effect. 


batch file 


String 


"(NULL)" 


An engine visible file to execute INSTEAD OF dis- 
playing any windows. 


display 


Function 




X display name. 


doc^dir 


String 


"doc" 


Directory where documentation files exist. 
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initialize 


String 


"display _report( 
\ main\ ) 


Expression to display initial report window. 
display ^report specifies the report that will be dis- 
played when the scpjui runs. An open_report com- 
mand is sent to the engine, which evaluates the 
display _report expression, display _report is always 

COmoiled on the etlPltlP. bpcaiiQP it tippHq tn rpnrl n npu/ 

report. 


laf 


String 


"windows" 


Look and feel for the nspr intprfapp Valnp mnct Hp r*r»p> 

of windows or motif. 


max_initial_height 


Integer 


1000 


Maximum initial height allowed for report window. 


maximum_initial_width 


Integer 


1000 


Maximum initial width allowed for report window. 


popup_messages 


Boolean 


TRUE 


If set to TRUE, display messages in popup window. 

If Set tO FALS1F Hl^nlav TTlPQCnOPC to ttif» tr»rminiil 


resize 


Function 


(NULL) 


One of GROW SHIFT GROW FTVFD nr 
GROWJFIXED_HORIZONTAL. 


splash 


Boolean 


TRUE 


If set to TRUE, briefly display logo window at startup. 


suppres s_table_ warning 


Boolean 


FALSE 


When TRUE, suppress the warning that occurs when 
the number of lines exceeds 1500. 


uncomputed_height 


Integer 


150 


Height allowed for uncomputed layout within a tab set. 


uncomputed_widlh 


Integer 


450 


Width allowed for uncomputed layout within a tab set. 


user 


Suing 


"(NULL)" 


Selects which report directories to use from the system/ 
user.dat file. Pretend our user id is this user. Only 
works for the user who started the engine. 


xzoom 


Float 


1.25 


Chart X axis zoom multiplier. 


y_zoom 


Float 


1.25 


Chart Y axis zoom multiplier. 
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2.4.5 Customize Options 

Table 6 lists the engine and UI options that are used to customize 
RHYTHM SCP and that are common to both the engine and UI executa- 
bles (scp_engine help all, scp_ui help all, and scpjbatch help all). Some 
are only for one or the other of engine or UI but not both (and are marked 
as such). 



Table 6: Customize Options - Engine and UI 
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absolute_pathnames 


Boolean 


FALSE 


If set to TRUE, prepend the current directory to relative 
pathnames If set to TRUE the $12 REPORTS/ envi- 
ronment variable in worksheet messages is replaced by 
the actual pathname. 


backup_prefix 


String 




When writing files, append this string to the beginning 
of the old file. Whenever a file is opened for write, and 
either this option or backup _suffix (or both) is a non- 
empty string, any existing file is renamed before the 
open smashes it. 


backup_suffix 


Siring 




When writing files, append this string to the end of the 
old tile. Whenever a rile is opened for write, and either 
this option or backup _preflx (or both) is a non-empty 
string, any existing file is renamed before the open 
smashes it. 


boolean_false 


String 


"OFfNn 


The set of characters which convert to "FALSE." The 
first character is used for output. 


boolean_format 


Function 


False, True 


Default format for Boolean values. 


booIean_true 


String 


"ITtYy-f" 


The set of characters which convert to "TRUE." The 
first character is used for output. 


buffer_size 


U- Integer 


8192 


ASCII file buffer size. 


char_format 


Function 


%c 


Default format for characters. 


classpath 


String 


"$I2_HOME/ 
i2jar:$I2_HOME/ 
scp.jar:/opt/ 
jrel.L5/lib/rtjar" 


Where to find Java classes $environment variables are 
substituted. 


debug__prompt 


String 


"Break {0} >" 


Prompt string for the OIL debugger. If the string con- 
tains '{0}', it will be replaced with the breakpoint 
name. 


default_format 


String 


"default" 


The default format to use for all controls. 


default_style 


String 


"Default" 


Style to use for attributes which nothing else specifies. 
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deleted_error_display 


String 


"<DEL>" 


What to display in a worksheet for the DELETED 
value. 


do_file_debug 


Boolean 


FALSE 


If TRUE, do_file reads at runtime instead of compile 
time. 


doc_changed_p 


Boolean 


FALSE 


Must be set to TRUE to document changed strings. 


file_type 


String 


"(NULL)" 


Default datafile extension 
(e.g. <dii>/<file>.<file_type>). 
Example: dat 


font_increment (UI only) 


Integer 


0 


Integer by which to increase / decrease all font sizes. 


it «,i 1 'iv a / / T TT i \r\ \ \ i \ 

galaxy ^ui orny ) 
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Arbitrary Galaxy options. 


gc„threshold 


U-Integer 


10 


Garbage collection threshold in megabytes. When 
exceeded, unused report memory is cleaned up. 


hexl6_format 


Function 


0x%04x 


Default format for 2 byte hexadecimal numbers. 


hex32_format 


Function 


0x%08x 


Default format for 4 byte hexadecimal numbers. 


hex8_format 


Function 


0x%02x 


Default format for 1 byte hexadecimal numbers. 


hex_format 


Function 


0x%x 


Default format for hexadecimal numbers. 


int_format 


Function 


%d 


Default format for integers. 


max_undo_changes 


U- Integer 


10000 


Maximum number of plan changes to undo. Higher 
limits cause more memory usage. 


new_user 


String 


"NewJJser" 


All new users inherit from this user. The default 
New_User gets its directories from the [unspecified] 
user 

When scpjui runs, and there is no entry in the user 
database for that user, the path in newjuser is copied. 
new_user can be useful when all users are to be started 
with a set of default reports. 
See separate section titled User for more details. 


nonexistent_error_display 


String 


tut 


What to display in a worksheet for the NONEXIST- 
ENT value. 


ptr_format 


Function 


0x%08x 


Default format for pointers. 


recurse_depth 


Integer 


1000 


Maximum recursion depth for the 'recurse' function. 


recurse_items 


Integer 


10000 


Maximum number of items computed in a recursive 
function before it truncates. 
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reference_error_display 


String 


"<REF>" 


What to display in a worksheet when using a cell value 
which has an error. 


report_parse_errors 


Boolean 


TRUE 


Must set to FALSE to turn off parse error reporting. 


seed 


Function 


TRUE 


seed for rand() functions. If set to TRUE, this option 
causes the random number generator to produce a con- 
sistent pattern each time it is run. The random number 
generator is used in making arbitrary choices. 


specfile_type 


String 


"spc" 


File type (extension) for specfiles. 


strict_conversion 


Boolean 


FALSE 


If set to FALSE, string->number conversions can have 
garbage at the end of the string. 


tab_width (UI only) 


Integer 


8 


Default tab width, in characters. 


timezone 


Function 


(NULL) 


Set thp T nral Timpyrmf* O ic TTTY" 1 fflrp^nwir-K ti™^ ^ 
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is CDT (Central Daylight). This option will more often 
be applicable to NT systems than UNIX systems 
because NT systems are sometimes not configured for 
the correct timezone. The default comes from the envi- 
ronment variable $12 JTIMEZONE. If this variable is 
not defined, then the default comes from the system. 


uncomputed_error_display 


String 


"<>" 


What to display in a worksheet for cells which are not 
computed. 


update_jnterval 


Float 


3 


Minimum of seconds before windows are automatically 
updated. 


value_error_disp!ay 


String 


"<VAL>" 


What to display in a worksheet for internals errors 
(overflow, etc.). 


while_max 


Integer 


4000000 


Maximum number of while loops before infinite loop 
error. 


worksheet_error_display 


String 


"<ERR>" 


What to display in a worksheet for worksheet formula 
errors. 



© 1998 i2 Technologies, inc. Proprietary Information March 27, 1998 



Rhythm SCP Customization Manual 2-45 



Engine and Ul Options 



Setup and Customization 



2.4.6 Connecting Multiple Uls to an Engine 

To authorize a client to connect to your machine, you can give him/her 
permission using the system/user \dot file. For example, when your log- 
inid on UNIX (where you run the engine) is John whereas your loginid on 
NT (where you run the client) is "John Doe" or "john doe". You would 
modify the system/user.dat and copy the New_User line as follows: 



All users of the UI must be registered in the system/user.dat file except 
the super-user (the user who started the engine). The super-user can run 
as anyone by using the user command line option. 

If a user's name does not appear in system/user.dat and a default 
New_User is not defined, then he is not given access to the engine. This 
is a security feature, as illustrated by the following example: 

Suppose a company is running two engines. Some users need to be 
restricted from accessing one of those two engines. This restriction is 
accomplished by forcing all users to be registered in user.dat. The only 
exception is the user who starts the engine. That user must have write 
permission to system/user.dat (or the save/restore file) in order to add 
new users. 



New_User; New User; 
John Doe; New User; 
john doe; New User; 



[unspecified]; 
[ unspecified]; 
[unspecified]; 



[unspecified] 
[unspecified] 
[unspecified] 



2.4.7 Security 
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2.4.8 Server Timeout 

To specify a time-out period for the server in case it should hang, you 
should use the server _timeout option. For example, in the following 
batch command, there is nothing to save if the engine is not running. The 
command hangs waiting for the engine, but the batch command times out 
after 120 seconds because the original command was run with the 
server Jtimeout option (default is 120 seconds): 

Original command: 

scpjui server jtimeout 
Batch command: 

scp_ui batch l save("scp_" & now & "J2")' 

Waiting for server on port 27111 



Error: Couldn't connect to server on port 27111 after 120 sec 
onds 
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2.5 Debugging in OIL 

Several helpful options are available for debugging purposes in OIL. 
These options debug faulty OIL code while RHYTHM SCP is running. 
Note: Appendix C has more information on debugging in OIL. The 
options include the following: 

■ Selecting a cell in layout and pressing <ShiftxF12> (invoking an 
OIL listener). This suspends the operation of the engine, producing an 
i2> prompt to handle a limited set of debug commands, or evaluation 
of variables in the layout. Commands available include the following: 

• print_variables 

• print_report_variables 

• inspect(modeMnstance) 

■ Setting flags in scp_engine.opt, such as: 

• command_execute: true; 

• action: true; 

These flags cause additional information to be printed when actions 
are taken in the UI. A few other helpful debug functions include the 
following: 

■ trace_usage (...) - this function is similar to the do function. It executes 
all of its parameters and returns the result from the last expression. In 
addition, it prints usage statistics about what was executed. 

■ trace_time (...) - this function is similar to trace_usage except that it 
only prints the time taken to evaluate its arguments. 

■ trace (String, ...) - this first parameter is a string which contains a list 
of trace flags to turn on or off. The rest of the parameters are expres- 
sions to evaluate the trace flags set. The trace flags are reset when the 
other parameters have finished executing. 

■ trace„echo (String, ...) - this function is used to print "Starting 
<string>" before evaluating the parameters or print "Finished 
<string>" after evaluating the parameters. 

■ report_text (String report_name, ...) - this function is used to print a 
report to stdout. 

■ layout_text (String layout_name, ...) - this function is used to print a 
layout to stdout. 
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■ inspect (modeMnstance) - this function, given a model instance, prints 
all of its fields and their values. 

■ echo - this function displays the result of any expression as long as it 
evaluates to a string or a symbol. Debugging with echo is good for 
layered debugging, tracking flows, and time stamping (use with the 
now function). 

Examples: 

buf f er_plans . f or„each { # . echo) returns the key field 
echo (true) echoes every statement and its results 

■ do_echo - this function displays the results of each of the expressions 
within a do. Debugging with do^echo allows you to gather timing and 
memory metrics for do statements. 
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section 3 Building a Report 



The first item of business is learning to build a report. Reports, as you 
have learned, are mechanisms for calculating and organizing planning 
data. They are created and managed in OIL and consist of two elements: 

■ Layouts 

■ Worksheets 

This section provides you with the information required to create a layout 
file {.lyi), a worksheet file (.wrk), and a report file \.rpi) for displaying the 
planning data. 
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3.1 Worksheets 



Worksheets are the computational platform for RHYTHM SCP. They are 
analogous to spreadsheets in that they are two-dimensional tables of 
cells. The cells within a worksheet contain values computed by OIL 
expressions. Worksheets primarily deal with data, however, they can also 
accept parameters. Worksheets differ from spreadsheets in that they do 
not specify how data are input, printed, or displayed. The RHYTHM SCP 
server holds the actual models and the worksheets are interposed between 
the server and the outside world (e.g. humans, data files). Each reports 
subdirectory contains ASCII files that are parsed and compiled as needed 
into RHYTHM SCP reports for that client/server combination. Work- 
sheets are defined (having the extension .wrk or .Jws for functional work- 
sheets) in those files. 

3.1 .1 Worksheet Types 

Three types of worksheets define data for use in OIL: 

■ Normal 

■ Replicating 

■ Functional 

A normal worksheet has cells which hold non-list values. It holds data 
such as strings, supply chains, #, etc. Normal worksheets are the default 
worksheet type. 

A replicating worksheet has cells which contain lists of values. Each cell 
within a replicating worksheet behaves like a normal cell that has been 
replicated, with each "copy" holding an element in the list. FIGURE 14 
illustrates the difference between normal and replicating worksheets. 

A functional worksheet behaves similarly to a replicating worksheet in 
that its cells can contain lists of values. However, the cells of a functional 
worksheet also execute sequentially. 
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Worksheets 



FIGURE 14 



Normal vs. Replicating Worksheets 




Normal cell containing the 
value A. 











a 











Replicating cell containing the list 
(al,a2,a3) 



3.1 .2 Worksheet Cells 

Worksheet cells are the basic component of a worksheet. They are simi- 
lar to traditional spreadsheet cells and are accessed via alphanumeric cell 
IDs (e.g. Al, J26). Worksheet cells can hold any RHYTHM SCP data as 
OIL expressions. 

In a normal worksheet, a cell can contain only a single value. In a repli- 
cating worksheet, a cell contains a list (even if it looks like a single 
value). A functional worksheet cell can contain either a single value or a 
list. 
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3.1 .2.1 Cells and Get/Set Expression 

Cells have expressions called get and set expressions. The get expression 
places a value into the cell. This value comes from either the engine or 
the outside world. Each cell must have a get expression even if it only 
returns nonexistent. The set expression writes a value from the cell to the 
engine. Explicit set expressions are not required. If a set expression is not 
present, RHYTHM SCP tries to deduce it from the get expression. For. 
example, if the outermost function is a settable field, RHYTHM SCP 
uses the set_ function to set it. If RHYTHM SCP cannot deduce the set 
expression, the cell is uneditable. 

get expressions are evaluated whenever: 

■ importing data 

■ interactive editing of planning data 

■ exporting data 

■ reading "read-only" portions of the user interface 

set expressions are evaluated whenever: 

■ importing data 

■ interactively editing planning data 

Note: Since the set expression can be any valid OIL expression, it is pos- 
sible to invoke all sorts of server and client behavior based on user 
inputs. 
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3.1.2.2 Get/Set Expression Syntax 

The proper syntax for get and set expressions requires a cell id and a get 
expression. The set expression is optional (as discussed previously). The 
syntax is shown below. Note: Interactive entries and imports are denoted 
in the set expression by #. Also, expressions within the < > are optional. 

[ cell = get_expression <, set_expression >; ] 

For example, 

[ B3 = site. description; 3 // B3 holds the 
value of site . description 

Here, the get expression is site . description and no set expression is 
provided. However, OIL will deduce a set expression as follows: 

[ B3 = site . description, site. set„description (#); ] 

so that if you modify cell B3, that data will be used to set the description 
field of site. 

As another example, consider holding the percentage of the committed 
forecast in an editable cell: 

[ Al = percentage ( forecast_entry. committed / 
forecast_entry. forecasted) ; ] 

Note that in the expression above, the cell is not editable. You must 
explicitly define a set expression so that a user can enter a percentage and 
have it update the committed field. For example, 

[ Al = percentage ( forecast_entry . committed 
/ f orecast_entry . forecasted) , 

/ /set expression f orecas t_entry 

. set_committed ( f orecast_entry 
.forecasted * percentage (#)) ; ] 
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3.1 .3 Dependent vs. Independent Cells 

A cell is dependent if its computed value depends on the value of another 
cell in the worksheet. For example, 

[ Al supply_chain = supply_chains . first ; ] 

[ A2 name - supply_chain . name ; ] 

[ A3 desc = supply_chain. description; ] 

Cells A2 and A3 are dependent on the value of cell A] and are hence 
dependent cells. Cell Al is an independent cell. 

In replicating worksheets, cell dependencies determine what layer the 
values reside on. If you have supply_chains named SI, S2, and S3, and a 
replicating worksheet such as: 

[ Al supply_chain = supply_chains . first ; ] 

[ A2 name = supply_chain . name ; ] 

[ A3 desc = supply_chain . description; ] 



Al 



A2 



A3 



Al 



A2 



A3 



Al 


A2 A3 


S2 


SC 


My 
Sec- 


SI 


SC 


My 
First 

















S3 


SC 


My 
Third 
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3.1 .4 Worksheet Syntax 

Worksheets require a particular syntax. This syntax is shown below: 



class name (<Type varl, Type var2 
declarations ; > 



. >) { 



[ <cell_id> <cell_name> = expression <;> ]; 



where class identifies the type of the worksheet (normal, replicating, or 
function procedure) and name identifies the name of the worksheet (iden- 
tical to the .wrk file name). The name of the worksheet can be omitted 
only if the layout specifies the worksheet to use (e.g. importjtextjile lay- 
outs). 

Cells may be assigned local cell names that act as aliases to the cell ids. If 
omitted, cell ids are automatically generated as the next cell in the current 
default column. Note: The cell id syntax from import files is NOT used 
outside of import files. For example, write Al not Al : . Also, do NOT 
use names such as Al, C12, K7, etc., to name anything but cells. 

FIGURE 15 displays the contents of site _context. wrk which illustrates 
the proper syntax for a worksheet. 



FIGURE 15 



Worksheet Syntax Example: site_context.wrk 



normal site_context (Site site) 
{ 

[ Al - "The Site: " ; ] 

[ Bl = site; ] 

[ CI = "of Supply Chain:"; ] 

[ Dl = Bl . owner ; ] 

[ El = "of engine: " ; ] 

[ Fl = engine_name; ] 

} 



Note: Unless otherwise specified, filenames cited in examples are in the 
. . Jreports/scp/ directory. 
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3.1.5 Worksheet Parameters 

Worksheet parameters have the following properties: 

■ Allow the worksheet to act as a template; the worksheet works for any 
values of the specified types. 

■ Are optional (e.g. if the worksheet is storing static information like a 
list of menu options). 

■ Are treated as local variables to the worksheet. 

■ Are the means of transferring information between worksheets. 

FIGURE 16 shows an example of worksheet parameters, where the nor- 
mal worksheet named, "Foo", has two parameters, x and n. 



Parameters Example 



normal foo (List [Site] x, 

Number n) 

{ 

[ Al _ x . element (n) ;] 



In the example above, x is a list of Site models, n is a number, and Al will 
contain the nth site in x. 
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3.1.6 Functional Worksheets 

Functional worksheets behave as replicating worksheets: their cells can 
hold replicated lists of values, and they can accept parameters. But unlike 
other worksheets, functional worksheets are designed to be directly 
invoked as functions from within any OIL expression. This is done using 
the OIL call function, which returns a result that is calculated by the 
invoked functional worksheet. 

Functional worksheets are the preferable method of creating OIL scripts 
(i.e. collections of OIL computations that can be invoked from batch cli- 
ents). They can also be easily invoked from within the OIL listener by 
using the call function. In this way, complex computations can be proto- 
typed in a functional worksheet and quickly tested from the listener. 

The following example shows the contents of a f\\c,first_op.fws, that 
defines a functional worksheet: 

function f irst_op ( String sc_str, String site_str) 
{ 

[Al SC = supply_chains . f ind(sc_str) ; ] ; 
[Bl MYSITE = SC . sites . find (site_str) ; ] ; 
[CI return = MYSITE . operations . firs t ;] ; 
} 

All functional worksheets impose a sequential ordering on evaluating cell 
get expressions. In this example, the worksheet accepts two string param- 
eters, and then uses them to calculate the contents of cells Al, Bl, and CI 
in sequential order. 

3.1.6.1 call Function 

The example functional worksheet above could be placed in a 
custom_reports directory and invoked from within an OIL expression as 
follows: 

call ( "$I2_REP0RTS/custom_reports/f irst^op" , 
"My Supply Chain", "My Site") 

The call function's first parameter names the .fws file that contains the 
function worksheet to be invoked, and the remaining parameters are 
passed to the worksheet itself. The result of the call is the Operation 
model calculated in the return cell (cell CI in this case). 
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3.2 Layouts 

A layout is a collection of controls. The type of the layout determines the 
type of controls allowed (e.g. bar^chart understands bar controls but not 
button controls). The control determines the properties of the associated 
worksheet cell in the parent layout. Common controls include button, 
checkbox, and general. 

A layout identifies which data is going into a report and how it will be 
displayed. The displayed data is contained within the worksheet file ref- 
erenced by the layout. Each layout refers to exactly one worksheet. A 
worksheet can be shared by several layouts (for data and computations). 
For example, the same data (Resource Utilization) can be displayed as a 
table or a bar chart. Layouts are parameterized via the underlying work- 
sheet. Thus, layout parameters are really just the worksheet parameters. 

Layouts can be nested inside each other. A layout that contains other lay- 
outs is called a parent layout. The layouts that are nested within a parent 
are child layouts. 

3.2.1 Layout Cells 

There is a one-to-one correspondence between the layout cells and the 
cells of the worksheet that the layout uses. Layout cell definitions are 
used to specify the display and layout properties of the cells. Layout defi- 
nitions include the following aspects: 

■ Controls - determines the display of the cells within reports 

■ Actions and Bindings - determines utilities attached to cells 

■ Styles and Formats - affects how the values in the cells are displayed 
(colors, number of digits, ...) 

■ Properties - defines various cell aspects (e.g. the protected property 
defines cells as uneditable). Properties include width, height, etc. 
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3.2.2 Specifying Layout Syntax 

Layouts do not define their own parameters. Since a layout refers to, at 
most, one worksheet, it passes arguments to that worksheet from the 
report that contains the layout (see 3.1.6.3 for an example). Layouts 
require a particular syntax. This syntax is shown below: 

layout_type name 
{ worksheet : ws_name ; 
<property: value; > 

< act ion: action_name = expression; > 

<bind: keystroke = action; > 

[ cell_id = <action: event - expressions 

<control: control_name (arguments ); > 

<bind: event = action; > 

<style: style_spec;> 

< format: f ormat_string ; > 

<protected: logical ;> 

<. . .> ] 
} 

where layoutjtype identifies the type of the layout, name identifies the 
name of the layout (identical to the name of the Ayt file), and worksheet 
declares the name of the associated worksheet, ws^name. Note: Often the 
layout (name) and worksheet (ws_name) names are the same, but this for- 
mat is not required when creating layout and worksheet files. Also note 
that there can be multiple property, action^ and bind statements. These 
statements do not necessarily have to be in that order. 
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FIGURE 17 displays the contents of active _strategy_context\y\ which 
illustrates the proper syntax for a layout, active _strategy_contextwrk is 
also shown to illustrate the relationship between layout and worksheet 
files. 



FIGURE 17 



Layout Syntax Example: active„strategy_contextlyt 



spreadsheet active_strategy_context 
{ worksheet: active_strategy_context ; 
[ Al = style: Context_Label ; ] 
} 



normal active_s trategy__context ( Active_Strategy active_strategy) 
{ 

[ Al = "The Active Strategy:"; ] 
} 




Contents of ; ■ '% - ■'■ ; , 
active_strategy„context.lyt 



J 




Contents of - 
active_strategy_context.wrk 



FIGURE 18 



The layout is of type spreadsheet. This means that the worksheet data 
will display as a two-dimensional table, with cell IDs determining data 
placement. In the example above, the string A J displays using the 
contextjiabel style and is located at the upper left-hand corner of the lay- 
out. 

FIGURE 18 displays the contents of seller _context.lyt as another exam- 
ple of a spreadsheet layout's syntax. This displays a horizontal row of 
data, Al through Dl. 



seller_context.lyt Example 



spreadsheet seller_context 
{ 

worksheet : seller_context ; 
[ Al = style: Row_JTitle; ] 

[ Bl = action: report = dispatch { w model_edit" ) ; ] 
[ CI = style: Row_Title; ] 

[ Dl = action: report - dispatch ( "model_edit" ) ; ] 
} 
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3-3 Reports 

Reports combine the worksheet and layout elements to define GUI Win- 
dows, Text Reports, and other client interfaces. Reports have parameters 
which allow the definition of the reports to be read and used by 
RHYTHM SCP without knowing ahead of time the specific model 
instances with which it will be working. The instance of the report cre- 
ated depends on the actual values that are passed as arguments to the 
report. Reports are maintained as ASCII files with the extension .rpt. 

FIGURE 19 shows the relationship between reports, layouts, and work- 
sheets. 



FIGURE 19 Interaction between Reports, Layouts, and Worksheets 




3.3.1 Embedding vs. Sharing OIL Elements 

Alternate syntax can be used to embed worksheets within Jyt files and 
layouts within .rpt files. 
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3.3.2 Specifying Report Syntax 

The syntax of reports is similar to that of import files. It should be noted 
that the layout declarations must be specified at the end of the file. This 
syntax is shown below: 

name (parameters) 
{ 

property: value; 

variable var iable_name = expression; 
compute compute_name = expression; 
action: action_name - expression; 
bind: keystroke = action; 
# include include_f ilename ; 
layout : layout_name (parameters ) ; 
[ layout properties ] ; 



} 

Note: There can be multiple property, variable, compute, and action 
statements. These statements do not necessarily have to be in that order. 

FIGURE 20 shows the contents of all _probs.rpt which illustrates the 
proper syntax for reports. 



FIGURE 20 Reports Syntax Example: alLprobs.rpt 




In the example above, RHYTHM SCP will look for the corresponding 
Jyt files in the $I2_Reports directory; if not found, the software will 
search other directories according to the sequence specified in user.dat. 
This same search approach is always used for OIL files (.rpt, etc.)- 
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The first line of the example specifies an expression that sets the title for 
this report. The remaining lines specify the order of layouts, one above 
the other, from top to bottom. 

The scpjile__menu layout will not be visible when the alljprobs report is 
initially displayed. Therefore, you will see three horizontal "strips": 
scpjmenubar, followed by supply „chain_context underneath it, followed 
by problem Jtistjate at the bottom. 

3.3.3 Reports Parameters 

Just like worksheets, 

■ Reports take any value type as a parameter. 

■ There is no limit on the number of parameters reports can take. 

■ The parameters are used as local variables in that report. 

For example: 

plan_editor (Plan the_plan) { 
layout: my_layout (the__plan) ; 
} 

In the example, the _plan is used as a local variable. 

Names of variables that are used to pass values to worksheets need not 
match the names of the worksheet parameters. For example: 

my_report (Number x) {layout: my_layout (x) } 

spreadsheet my_layout { worksheet: my_worksheet ; } 

normal my_worksheet (Number y) { [ Al = y; ] > 
//y will get the value of x 

In the example, the parameter jc of myjreport will be passed to y in 
my ^worksheet via the invocation of myjayout. 
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3.3.4 invoking Reports 

Reports are displayed by invoking the display jreport function 
(display jreport (" report jiame", parameters);). Example uses of this 
function are shown below, 

■ with actions defined in cell controls 

E El - action: report = display_report { "planjaditor" , 

supply_chains . first 
.plan. first) ; ] 

■ on UI startup 

scp„_ui \ 

initialize ' display ^report { "planjsditor" , \ 

supply^cha ins . find {"Super Metals") 
.plans. find ( "Actual Plan")}' 

3.3.5 Reports of Importance 

Two standard (i.e. \2 written) reports of special importance exist. These 
reports are listed below: 

■ application.rpt - found in the basic reports directory. It contains most 
of the default and standard actions, definitions, and bindings. All 
reports inherit the actions, bindings, and variables defined here. Note: 
There is no screen associated with application.rpt. 

m main.rpt - the default main window definition (may be overridden 
using the scpjii initialize option). 



Note that read_changedj)iljiles does not work with these two reports 
only. The only way to see changes to these two reports is to restart the 
engine. 
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3.3.6 Scoping Rules 

Reports can only access the following data: 

■ input parameters 

■ variable and compute declared within the report 

■ parameters passed into the report 

Worksheets can only access the following data: 
m input parameters 

■ variable and compute declared within the worksheet 

■ parameters passed into the layout 

Layouts can access the following data: 

■ all the data from their associated worksheet 

■ input parameters 

■ variable and compute declared within the worksheet 

Report parameters are passed by reference. Therefore, each report gets 
its own copy of the input parameters. This limits the changes a report can 
make to be within its own scope. 

Worksheet parameters, in contrast, are passed by reference. Therefore, if 
the same value is passed to more than one worksheet, then worksheets 
share data. This allows a change made in one worksheet to affect other 
worksheets in the report (i.e. the worksheets stay in sync). 

You might refer to our parameter passing as "conditional reference". If 
the actual parameter is a variable name, the parameter is passed by refer- 
ence; otherwise, it is passed by value. This is true for all calls that pass 
parameters. 

In the example shown in section 3.3.3, if x changes its value within 
myjreport, then y will change its value within myjworksheet. 
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3.4 Computed Properties 

Most properties in worksheets, layouts, reports, import worksheets, and 
export worksheets can be expressions. For example, you can pass the 
filename(s) to be read from to an import worksheet as a parameter. OIL 
automatically tries to figure out which properties are expressions and 
which are constant, but sometimes it cannot tell. To force a property to be 
computed, use two ":"s instead of one. For example, instead of: 

file : file; // File will be "file" 

use 

file : : file; // File will be the value of the 'file' variable 

The following is an example if passing a filename as a parameter to an 
import worksheet: 

File: supply__chain . imp 

import_text_f ile supply_chain 
{ 

worksheet (string file) 
{ 

model: "Supply_Chain" ; 
this = supply__chains ; 

[Al : name = #;] 

[Bl: description - #;] 

} 

file : : file; 
import_record: Al Bl; 
} 
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3.4.1 List of Computed Properties 

The following properties can be specified as computed properties: 




«.= % sv.cc- .,:.'«< "" • - J** ■ K -V^'.frP£*>j-- %} ■ ^ T^i^.- S 
. i : iVv.- ! iv : .'" v>^: V ^IftV;-??/,*-; -'^/; 1^>f • 


visible, compute_when„visible, count, disable, protected, 
growth_factor, default_rows, default_cols, point_width, 
pointjieight, description, remark, no_scroll, x_scroll, 
y_scroll, x_stretch, y_stretch, multi_select, tab_set, tab_title, 
tab„icon, layout_name, width, height, dynamic_cell_sizes 


layout 


x_synch, y_synch, x_range, y„_range, hide Jeft_axis, 
hide_right_axis, hide_top_axis, hide_bottom_axis 


univ_chart 


y, x, cross, sort, sparse, totaLdown 


axis_cross 


always_recalc, title, icon, description, remark, fast_update, 
auto_update, hide_disabled_layouts, modal 


report 


title, icon 


application 


import_record, import, delimiter, file, fixed_width, sequence, 
optional, before_import, after_import 


import_text_file 


import_record, import, sequence 


import_rhythmlink 


delimiter, tile, iixed_width, belore_export, arter_export, 
title_line_prefix, sequence 


export_text_file 


x_synch, x_range, y_synch, y_range, hide_bottom_axis 


gantt_chart 


x_synch, y_synch, yjange 


bar_chart 


foreground_color, background_color, format, border_color, 
pattern, pattern_color, h_align, v_align, invert, font_family, 
font_style, font_size, border_style, border_top, border_right, 
border_bottom, borderjeft, width, height, disable, hide, pro- 
tected, modal 


style 


foreground_color, background_color, font_family, font_style, 
font__size, disable, hide, width, height, protected, left_inset, 
right_inset, top_inset, bottom_inset 


item (Note: these dialog items 
only support a subset of style) 


image_name, image_position 


image_general 


max_initial_level 


outline_general 


image_name, vertical, center, draw_label 


button 
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imaae name action name tiD 


tool button 


dirtv imaffe name 


undate tool button 


lavout name exclusive 


combo noodown 


lavnnt name exclusive 


comouted combo DODdown 


minimum maximum 

1111111111U 1X1, llillAllllUili 


slider 


minimum maximum 

111 1 1 1 1 1 1 1 lilll^ llJUAlllllilll 


sninner 


InVipl tmp 1aV*f*1 f?ilsf label 


checkbox 


label 


radio_button 


action_name, label, license^package 


menu item 


layout_name, label 


submenu 


layout_name 


usejayout 


bar_label, bar_color, width, height, stack_set 


bar 


y, x_synch, y_synch, x__range, y_range, sort 


line_chart 


format 


secondary_axis 


format 


time_buckets 
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3.5 Guidelines for Formatting Reports 



The following report formatting guidelines enable the user to write 



3.5.1 Layout Declaration and Invocation 

When defining a layout function within the .wrk file, place the first 
parameter on the same line as the layout name and all succeeding param- 
eters directly below the first parameter, one parameter per line. For 
example, 



reports which are efficient and easy to read. 



replicating mpp_items„category_summaries (Plan plan, 



Site_Plan mpp_site_plan, 

Item mpp_i tern, 

Symbol category, 

List [Date_Range] bmcket_l is t , 

Logical l_demand, 

Logical l_starting_oh, 

Logical l_planned, 

Logi cal l_change , 

Logical l_ending_oh) 
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The look of the layout when called from the .rpt files should be similar: 



layout: . mpp_items_category_summaries (plan, 



The advantages of following these formatting tips are as follows: 

■ makes determining the number of arguments of a list and mapping 
their type from the calling location to the declaration easy 

■ makes separating the parameters from their values quick and simple in 
the invocation since the tab information is aligned 

■ makes scanning through the .rpt files to see how many layouts exist 
exponentially easier since the word layout is the only one in the left- 
most column area 




mpp_site_plan, 

mpp_item, 

i tem_category , 

bucket_list , 

l_demand , 

l_starting_oh, 

l_planned, 

l_change , 

l_ending_oh ) 



[ tab_set : 
tab_title 
count : 



tabs ; 

Items of a Category; 
nonexistent ; 
product ; 
FALSE ; ] ; 



tab_icon : 
disable : 
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3.5.2 Appearance of compute Functions 

computes can be difficult to format efficiently within .rpt files. The fol- 
lowing format works efficiently for computes: 

r 

compute check for site plan = 

if (and (current_site_plan == mpp_si te_plan, 

current_site_plan . owner = = mpp_s ite_pl an . owner ) , 
current_si te_plan, 
do ( set_variable (mpp_item, 

mpp site plan. site . items . filter { # . name == 

mpp_i tern. name) .first ? 

mpp_site_plan. site . items . first) , 
if(mpp_item == nonexistent, 

set_variable ( item_category , nonexistent) ) , 
set_variable (current_site_plan, mpp^si te_plan) ) ) ; 

In the above example, the first line of the actual computation appears 
below the name of the compute itself. This provides between ten to thirty 
extra columns to work with and maintains the compute clear in the left 
column for easy visual access. 

On a more general level, if and, do, etc., statements should contain only 
one argument per line and they should be aligned to the "(" of the state- 
ment. This is a good general rule to follow (even if you can fit more than 
one argument on a line) because when the file is edited, the beginning of 
each line following a do statement can be quickly scanned to determine 
the arguments. Note: Some arguments will take up more than one line, as 
seen above. This cannot be avoided. 

An eighty column maximum should be adhered to whenever possible, 
falling back to one hundred only when there is no clean way to break a 
statement up into two lines. This is done because eighty columns is a 
much more common standard than one hundred columns. 



A final guideline for this section is to remember to use whitespace. 
Whitespace, when used properly, improves the presentation of informa- 
tion. 
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3.5.3 General Layout of .rpt Files 

The following format should be followed when creating .rpt files: 



report declaration ( ) 
{ 

remark : 

yaddayaddayadda 



; //end of remark 



[variable and compute section] 



The variable and compute section should be staggered as follows: 



variable current_site_plan = sp; 

compute check__site_plan = if (current_site_plan != sp, 
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If the variables and computes are grouped according to function rather 
than structure, the groups are easier to find and change when updates are 
needed. For example, 



// Initializations 

variable plan = sp . owner; 
variable mpp site plan = sp; 

variable mpp_item = mpp_sitej)lan. site . items . first ; 

// Synchronizations 

variable current__plan - plan; 

compute check_plan = 



if (current plan != plan, 

do (set_variable (mpp„site_plan, plan. site_plans . first) , 

set_variable (mpp_item, mpp_site_plan . site . items . first ) , 

set_variable(current_plan, plan)} 
current_plan) ; 



variable current_site_plan = mpp_site plan; 
compute check_site_plan - 

if (mpp„site_plan != current_sitejplan, 

do (set_variable (mpp_item, mpp_site_plan . site . items . first ) , 
set_variable (current_site_plan, mpp_si te_plan) ) , 
current_site_plan) ; 

etc .... 

[ action section ] (if any, some have it some don't) 

[ layout section ] 
[ menu includes ] 
[ invisible layouts ] 
[ context layouts ] 
[ selector layouts ] 
[ tabsets ] 




include files should be placed in the most appropriate section. For exam- 
ple, 



buckets. act would go in the actions section 

planning, mnu would go in the context and selection section 

main_reportvar would go in the variable section 



© 1998 i2 Technologies, inc. Proprietary information 



March 27, 1998 



Rhythm SCP Customization Manual 3-25 





Guidelines for Formatting Reports 



Building a Report 



3.5.4 Placement of Comments 

Each section shown in the previous example should have a brief one- line 
comment marking the beginning of the section. The action section should 
be further subdivided, as shown below: 



A remark should always be included. 

3.5.5 File Naming 

.rpt files consist of the full name of the report, with underscores separat- 
ing words (i.e. master production plan.rpt). .lyt and .wrk files append 
the initials of the report name to the layout and worksheet files. This 
causes the files to be listed together in the directory list and makes it eas- 
ier to determine which files go where. For example, 

date_editor, rpt 

de_monthjyear. lyt 
de_month_year. wrk 

Since not all report initials are unique (as with master production _plan 
and master purchase plan) pick an arbitrary but logical set of initials to 
differentiate them (i.e. mpp and mpc). The only exceptions to this should 
be files that are used in more than one report, like plan_aux_context. 



//popup menu actions 
action : ... 



//button actions 



action : 
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3.5.6 .wrk and .lyt Files Layout 

The following guidelines should be followed for .wrk and Jyt files: 

■ Within . wrk and Jyt files, provide cells with names in addition to their 
location and refer to them by name in the Jyt files. For example: 

in the .wrk file: 

[ Al bob - .... ] 

[ Bl cooper = .... ] 

[ CI truman = .... ] 

[ Dl leland = .... ] 

in the Jyt file: 

Y: bob cooper truman leland 

Comprehending what is actually displayed is much easier this way. 

■ Place only one parameter/flag per line in the cell definitions: 

[ E6 = width: 10; 

height: 10; ] 

■ Multi-statement actions should line up similar to the compute guide- 
lines: 

[ E3 = action: select = 

do (set_variable (chosen_f ilter , "AUP" ) , 
set_variable(last^filter, chosen_f ilter ) , 
set_variable (chosen_rp, chosen_f ilter) ) ; ] 

■ As a general rule, separate column cell declarations by at least one 
line: 

[ C2 = action: select = 

do (set„variable (chosen_rp, "ARP" ) , 
set_variable (chosen_f ilter , "")); ] 

[ C3 = action: select = 

do (set_variable (chosen_f ilter , last_f ilter) , 
set__variable <chosen_rp, chosen_f ilter) ) ; ] 



[ D3 = control: radio_button ( " " ) 
[ D4 = control : radio_button ( " " ) 
[ D5 = control : radio„button ( " " ) 



[ E3 = action: select = do { set_variable ( chosen_f ilter , "AUP") 

set_variable ( last_f ilter , 

chosen_filter) , 
set_variable (chosen_rp, 

chosen_f ilter ) ) ; ] 
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m Some additions for OIL files in general: 

• Try not to make your lines more than 80 characters. Lines that wrap 
are hard to read and debug. Starting continued lines with a period 
enables a user to determine (at a glance) that they are continued from 
above. 

• This 80 character limit applies to comments as well. If the comment 
is going to be too long, break it and start another comment line. 

• Take into consideration that not all users looking at files have the 
same amount of experience. Comments should tell why as well as 
how. 

Some examples: 

// This expression will find and delete all the operation plans that were 
// generated to fulfill the requests that are going to be cancelled. 

requests . f or_each ( # . delivery_requests ) 
. f or_each ( # . item_requests ) 
. for_each ( list (# . delivery_j?lan 
- top_operation_plan, 

# . receiving_plan . top_operation_plan) ) 
. f or_each (#. delete ) ; 
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section 4 Applying Controls, Formats, and 

Styles 



You are now going to learn how to apply controls and formats to the 
basic reports you learned to create in section 3. (It is important to note 
that when using controls and formats the syntax must be exact. The 
parser will "stumble" over things such as a space between a declaration 
and its colon.) FIGURE 21 illustrates the relationship between reports 
and controls, formats, and styles. 



FIGURE 21 



Components of Reports 
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4.1 Controls 



Controls are the individual display elements of a layout. The type of lay- 
out determines the controls available to comprise that layout. The control 
for a cell is responsible for the cell's rendering, whereas the cell is 
responsible for the data to be rendered. 

Controls are broadly characterized as Chart, Table, or Text controls. (See 
the RHYTHM SCP Model Reference Manual for more information.) 

4.1.1 Available Controls 

The following is a list of all available controls: 



bar 


list_bar 


button 


map_connect 


checkbox 


map_node 


combo 


menu_item 


combo_popdown 


menu_radio_item 


filler_bar 


outline_general 


gantt_axis 


percentage_bar 


gantt_bar 


radio__button 


general 


separator 


indented_general 


slider 


label 


spinner 


layout 


submenu 


line 


time„buckets 


line__rate 


tool_button 


line_step 
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4.1 .2 Common Controls 

There are several controls that are commonly found or used within 
reports. Table 7 below lists these controls with a brief description: 



Table 7: Common Controls and Their Descriptions 





' < ' •• V • ■' ■•■•;:•••■•..*■ .aig^^^ift^g -^XVjw-V^ri. m ^tu. ! # T^^k'- ^ '■ ' foV-.-y^, 

; <?.>; : ,v :; -vr:-.;. :.v ^ s-^tii-j^,;.-; • •. - - -j.-?- , ;■■>■■ . ; ^.- : vrfe JT-. ; .-, ; y v-j ./>. u r * •: v.-, . - : „ : ..-' i:":; v ; ; .:;R,-Vi- v-;.« 


button 


• Displays the cell as a button that can be depressed to invoke an action. 

• When given no arguments, this control displays the associated cell value as the 
button label. 

• When given a string and two Logicals, the cell does one of the following: 

• displays the associated cell value as the button label 

• displays the icon named by the string parameter 

• if the first Logical is true, then the label appears below the icon; otherwise it 
appears to the right of the icon 

• if the second Logical is true, then the icon and label appear centered inside 
ine DUiion 

• When this control is given a string and three Logicals, the behavior is the same 
as above except that when the third Logical is false, the button label does not 
appear at all. 

• The button is inactive (greyed-out) when there are no actions defined for it. 


checkbox 


• Displays as a square button that is toggled based on the associated cell value 
which must be of type Logical. 

• The checkbox is intended for use as "choose any of many". However, check- 
box by itself does not implement "choose any of many" behavior. (See 

site _plan_editor.lyt for an example of how such behavior is written in OIL.) 

• When the checkbox is invoked with no arguments, the checkbox titles are 
determined by the format for the type Logical. 

• When the checkbox is invoked with one String argument, the string is used as 
the checkbox label. 

• When the checkbox is invoked with two String arguments, the string are used 
as the on and off labels. 
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5^?^v : v? ^*tfiri *f-i* cm 




combo_popdown 


• Displays a list of values that the cell may be assigned in a combo _popdown 
list. 

• When invoked with no arguments, the list of values is determined by the value 
represented in the associated cell. For example, [ A6 = m Y _site.roie; ] 

// shows link, supplier, customer in the combo _p opdown list. 

• When the combo _popdown is invoked with a single String argument, the list of 
values is determined by the layout named in the string. The layout is usually 
an axis cross with a single column. (See resource _j)lan_chooseJllters.lyt for 
an example of how this behavior is written in OIL.) 


general 


• Displays the cell as an ordinary cell with the specified format (e.g. general 

( "my_format" ) ). 

• The general control is the default control for spreadsheet and axis cross lay- 
outs. 

(See resource jutilization.lyt for an example.) 


indentecLgeneral 


• Displays the cell as an indented list. 
(See group _f or ecasts.lyt for an example.) 


label 


• Displays a String and does not cause any behavior on GUI events. 


layout 


• Displays layouts within layouts by specifying them as controls. 

• Layout accepts a parameter that is the name of a layout. 

• Allows layout arrangements other than the default top-to-bottom arrangement. 
(See mainjbodydyt for an example.) 

• Layout allows for the inclusion of multiple layouts within a tab. (See 
plan_prohlemsJ.ab.lyt for an example.) 


outline_general 


• Displays the cell as an indented list with outline controls (e.g. Main Explorer 
navigator). 


radio_button 


• Displays as a circular button that is toggled based on the associated cell value, 
which must be of type Logical. 

• Accepts a String parameter to be its label. If the parameter is the empty string 

then no label is shown. 

• Radiojbutton is intended for use as "choose exactly one of many". However, 
radio_button by itself does not implement "choose exactly one of many" 
behavior. (See .../reports/basic/exit_dialog.lyt for an example of how this 
behavior is written in OIL.) 
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Table 7: Common Controls and Their Descriptions 







tool_button 


• Displays as a button within a toolbar. 

• Can only be used in toolbar layouts. 

• Its three parameters identify the image, the action, and the tooltip string. (See 
scp _plan_toolbar.lyt for an example.) 



4.1.2.1 Specifying Control Syntax 

Controls require a particular syntax. This syntax is shown below: 

control: control_name (control_parameters); 
For example: 

[ Al = control: slider(0, 1); ]; 
There are exceptions to this syntax. They are as follows: 

[ bar(cell_id); <property>, <...>; ]; 

[ axis - gantt__axis(cell_id); ]; 

[ axis - timeJbuckets(celLid); ]; 
These are the only three controls that use different syntax. 



© 1998 i2 Technologies, Inc. Proprietary Information March 27, 1998 



RHYTHM SCP Customization Manual 4-5 



Controls Applying Controls, Formats, and Styles 



4.1.3 Chart Controls 

Chart controls are used in bar_chart, gantt_chart, and map„chart layouts 
They can only be used within these types of layouts. The different chart 
controls are as follows: 

■ bar 

■ gantt_axis 

■ gantt_bar 

■ line 

■ line_rate 

■ list_bar 

■ map_connect 

■ map_node 

■ time_buckets 
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Controls 



4.1.3.1 



bar 

The bar control is displayed as a bar in a bar_chart layout with a label and a 
value. The control expression for a bar control would be as follows: 



[ bar(Fl); style: Barl ; width: 30; ] 



The entire set of bar controls might appear in a bar^chart layout named 
revenue _cost_bar_chart. The layout file revenue _cost_bar.lyt and its corre- 
sponding worksheet file are shown below. 



/ /Layout 

bar_chart revenue^cost bar_chart 



worksheet : revenue_cost_bar_chart ; 



[ axis: time_buckets (B2 ) ; ] 

[ bar(Fl); style: Barl; width: 30; ] 

[ bar(F2) ; style: Bar2 ; width: 40; ] 

/ /Worksheet 

replicating revenue_cost_bar_chart (Plan plan, 

List [Date_JRange] 
bucket_list ) 

[ head = "Revenue-Cost Bar Chart"; ]; 

[ Bl dates = bucket_list; ] ; 
[ B2 dates = dates, start; ]; 

[ Fl cost = plan. site_plans . filter (#.site 



[ Fl. title = "Cost"; ]; 

[ F2 revenue ^ plan. site_plans . filter (jf .site 



.managed) 

- for_each(# . supply„request) 

. filter (within 

(#. accepted, dates)) 

. for_each (# . delivery_requests ) 

. for^each ( # . delivery promise) 

. for_each (#delivery_price) .sum; ] ; 



.managed) . f or_each 
( # . supply_request) 

. filter (within ( # . accepted, dates ) ) 
. f or_each ( # . delivery^requests) 
. f or_each ( # . delivery_promise) 
. for_each(#delivery_price) .sum; ] ; 



[ F2. title = "Revenue"; 



; ] ; 
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4.1 .3.1 .1 axis Property 

One cell in the bar_chart layout must be preceded by the axis property. 
This specifies the cell values used to label the bottom X axis of the chart. 
Also, the remaining cells (used as bars in the chart) must be dependent on 
the cell used as the axis. 

4.1.3.1.2 bar^col or Property 

For each bar within a bar„chart layout, if the bar_color value is set, its 
string value is used to set the foreground color of the bar. This property 
can be used in conjunction with the stack_set property to set the colors of 
the individual values. 

4.1.3.1.3 bar label Property 

The barjtabel property allows the user to set the label for the bar. If this 
property is not set, the label is derived from the bar value. 

4.1 .3.1 .4 stack_set Property 

Individual values displayed with the bar control may also be stacked 
using the stack_set property. Using the example from above, Dl and El 
could be stacked as follows: 

[ bar (Dl); style: Barl; width: 30; stack_set: "stackl"] 
t bar (El); style: Bar2; width: 40; stack_set: "stack 1"] 

All cells given a stack_set property with the same string value are stacked 
together. 
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Controls 



4.1.3.1.5 Bar Values 



At present, the only control allowed to follow the axis property in a bar 
chart is the timejbuckets control. For displaying bar values, two controls 
are available: 

■ bar (value_cell) - plots a single cell value in a single bar 

■ list„bar (value^cell, name^cell) - plots a cell containing a list of values 
as a stacked bar using name_cell for colorization and popup tips. 

The bar control is colored using the style property for that cell. The 
list_bar control expects a cell containing a list of values and will display 
a single bar with all values stacked. The second parameter must be a list 
of equal length containing strings used for colorization. The string is not 
a color name but the name of the object being plotted. For example, if the 
control is displaying the time used at a resource for producing a variety of 
products, the first listjbar parameter would be a time quantity and the 
second para-meter the name of the product. The bar_chart will then 
ensure that each product named Widgetl displayed in any chart will be 
drawn with a consistent color. 



The following default actions are invoked from the bar control: 

■ Select 

■ Menu 



4.1.3.1.6 Associated Actions 
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4.1.3.2 fillerjbar 



fillerjbar is a bar_chart control that behaves similarly to the bar control 
except that it is invisible and cannot be selected. This control is used within 
a bar_chart layout using the stack_set property to display an empty or 
blank space within the bar. The control expression for filler Jbar would be 
as follows: 

[ f iller_bar (on_time) ; property: stack_set = "uno"; ] 
The fillerjbar control might be used in a layout name filler Jbar _chart.lyt: 

/ /Layout 
bar_chart f iller_bar_chart 

{ 

worksheet : simple_resource_load; 
[ axis: time_buckets ( time ) ; ] 

[ bar (early); property: stack_set = "uno"; style: Early; ] 

[ £iller_bar(on_time) ; property: stack_set = "uno"; ] 

[ bar (late); property: stack„set = w uno"; style: Late; ] 



} 



//Worksheet 

replicating f iller_bar_chart (Plan plan, 

List [Date_Range] 
bucke t_list) 
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4.1.3.3 gantt_axis 

The gctntt^oxis is a gantt_chart control that specifies the list of objects 
used to label the Y (vertical) axis, and contains the data referenced by the 
ganttjbar controls. 

At present, the only control allowed to follow the axis property in a 
gantt_chart is the gantt_axis control. The control expression for a 
gantt_axis control might be as follows: 

[ axis: gantt_axis (buf f er ) ; ] 

The gantt^axis control might appear in a gantt chart layout named 
buffer _gantt_charUyt. The layout file buffer _gantt_chartlyt and its cor- 
responding worksheet file are shown below. 

/ /Layout : 
// 

gantt_chart buf fer_gantt_chart 
{ 

worksheet : buf f er_gantt_chart ; 
[ axis: gantt_axis (buf fer) ; ] 

[ gantt_bar (operation, start, end, f low_plan) ; 

action: select = set_variable (dr, flow_plan . dates) ; ] 

} 

/ /Worksheet 
// 

replicating buf f er_gantt_chart (List [Buf fer^Plan] bps, 

Date_Range dr) 

{ [ head = "Gantt Chart"; ]; 

[ buf fer_plan = bps; ] ; 

[ buffer = buf fer^plan.buf fer ; ] • 
[ buffer. title = "Buffers"; ]; 

[ flow„plan = buf fer_plan. f low__plans (dr ) ; ]; 
[ operation = flow_plan . owner . operation ; ]; 
[ start = f low_plan. dates . start ; ]; 
[ end = f low_plan . dates . end ; ]; 
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4.1 .3.4 ganttjbar 

The ganttjbar control is a gantt_chart control used to specify the data 
used in plotting the bars within a gantt chart. The expression of the 
gantt_bar is a replicating worksheet, and is just one load plan when 
referred to in an action expression. The control expression would be as 
follows: 

[ resource = rp . resource () ; control: gantt_bar ( w " ) ; 
width: 24; ] 

The Gantt_Chart lays out the bars in the minimum number of rows. This 
increases the effectiveness of the Gantt_Chart for shared use resources 
(the user can easily see where he is overloaded). This is done by sorting 
by start date and then laying out each bar in the lowest row whose last 
end data is before that start date. 

The entire set of ganttjbar controls might appear in a gantt_chart layout 
named resource _gantt_chart.lyt. The layout file resource _gantt_chartlyt 
and its corresponding worksheet file are shown below: 

/ / Layout : 
// 

gantt^chart resource_gantt_chart 
{ 

worksheet : resource_gantt_chart ; 

action: on_layout_hide - set_variable (bucket, 

buckets .first) ; 
[ axis: gantt_axis (resource) ; ] 

[ load plan = action: select = set_vari able (bucket , 

1 oad_pl an . dates ) ; 
action: move_in - r es ou r c e_p lan .move ( load_p lan, 

true, false, false) ; 
action: mo ve_ i n_ou t - resource plan . move ( load plan, 

true, true, false) ; 
action: move_out = resource_plan .move ( load_plan, 

false, true, false) ; 
action: move_in_or_of f = resource_plan . move ( load_plan, 

true, false, true) ; 
action: move_out__or„of f = resource_plan 

.move(loadjplan, false, true, 

true) ; 

action: move = resource j»lan . move ( load_plan, true, 

true, true) ; ] 
[ gantt_bar (operation, start, end, load plan) ; 
action: select = set_variable (bucket , load_plan . dates ) ; 
action: move_in = r es our ce_p lan .move ( load _s> lan, true, 

false, false) ; 
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action: move_in_out - resource j)lan . move ( load_plan , 

true, true, false) ; 

action: move_out - resource_pl an .move ( load „plan, false, 

true, false) ; 

action: move_in_or_off = resource_plan . move ( load_plan , 

true, false, true) ; 

action: move_out_or_of f = resource_plan .move (load_plan, 

false, true, true) ; 

action: move = resource plan .move f load plan, true, true, 

true) ; } 

} 

/ / Worksheet : 
// 

replicating resource_gantt_chart (List [Resource^Plan] rps , 

List [Date_Range] buckets , 



{ 



Datejange bucket) 

[ head = "Gantt Chart"; ]; 
t resource_plan = rps; ] ; 

[ resource - resource, plan . resource ; ]; 

[ resource. title - "Resources"; ] ; 

[ load plan = resource_plan . load_plans ; ]; 

[ operation = 1 oad_pl an . owner . operation; ],- 

[ start = load_j?lan . dates . start ; ]; 

[ end = load_plan . dates . end; ] ; 



One cell in the gantt_chart layout must be preceded by the special axis 
property. This indicates that the cell values should be used to label the 
left axis of the chart. Also, it is required that the remaining cells (used as 
bars in the chart) are dependent on the cell used as the axis. 
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4.1.3.4.1 



Parameters 



For displaying gantt bar values, only the ganttjbar control is valid. It 
accepts four positional arguments: 

■ model_value - the model on which the model menu should act 

■ start_date - a date used as the gantt bar start value 

■ end_date - a date used as the gantt bar end value 

■ color_value - the tag used to select a color 

When actions are run, the action focus is the cell specified by the 
action_obj parameter of gantt Jjar. 



The following default actions are invoked from the ganttjbar control: 

■ Select 

■ Menu 



4.1.3.4.2 Associated Actions 
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4.1.3.5 line 



The line control is a line_chart control. To get up-down-horizontal lines 
in a graph, use the line_rate control. If you use line or line_step, the 
graph lines may be sloping. The control expression for this line control 
would be as follows: 

t C2 = style: Barl; control: line ( ) ; ] 

The line control might appear in a line_chart layout named 
buffer _pn_handjiine_chart. The layout file 

buffer _on_hand_line_chart.lyt and its corresponding worksheet file are 
shown below. Note that it is possible to have multiple line controls on a 
single row. 

//Layout 

line„chart buf f er_on„hand_l ine„char t 

worksheet : buf f er_on_hand_l ine_char t 
[ C2 = style: Barl; control: line ( ) ; ] 

//action: select = do ( set_variable 
selectedjoucket , f p. dates) ) ; ] 
[ C2. title = style: Row_Title; ] 
[ D2 = style: Bar2 ; control: line ( ) ; ] 
[ D2. title = style: Row_Title; ]; 

y: c2, c3, d2 , d3 ; 

//Worksheet 

replicating buf f er_on_hand_l ine_chart (Buf f er_Plan bp, 

Date„Range selected bucket) 

[ head = "On-Hand Line Chart"; ]; 

[ CI fp = bp . f low__plans (.selected_bucket ) ; ]; 

[ C2 date = if { fp .produced , f p . dates . end, 

fp . dates . start ) ; ]; 
[ C2 . title = "Planned On Hand"; ]; 
[ C3 on_hand - bp . on_hand ( f p ) ; 3; 
[ D2 min_date = list ( selected„bucket . start , 

select ed_bucke t . end) ; ] ; 
[ D2. title - "Min On Hand"; ]; 
[ D3 min_on_hand = do (min_date , bp. buffer 

. min_on_hand ( ) ) ; ] ; 



4.1.3.5.1 Associated Actions 

The following default actions are invoked from the line control: 



■ Select 



■ Menu 
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4.1 .3.6 line_rate 

line_rate is a line„chart control which consumes three values (that of the 
current cell, and those from the next two columns). The values are: jc, y y 
and rate (i.e. slope). These values are consumed in the stated order. For 
each point, a line is drawn from the previous x/y point to the current x at 
the slope specified by the previous rate value. From there a vertical line 
is drawn to the current y. 

Note: The quantity units for line_rate must be appropriate for the math 
required. For example, if x is <time>, and 37 is <mass>, then the slope 
must be in units of <mass>/<time>. 

The control expression for the linejrate control might be as follows: 

[ date - control : line„rate ( ) ; ] 

The line_rate control might appear in a line_chart layout named 
eff_line_chart.lyt. The layout file eff_line_chart.lyt and its corresponding 
worksheet file are shown below. 

// Layout 

line_chart ef f_line_chart 
worksheet: ef f_line_chart ; 

[ date = control: line_rate ( ) ; ] 

[ value ~ ; ] 
y: date value rate; 
visible: false; 

/ /Worksheet 

replicating ef f_line_chart (Resource^Plan rp) 
[ head = w Eff Line Chart" ] 

[ pp = rp. ef f iciency_prof ile (rp. owner . owner 

.horizon) ; ] 
[ date = pp. date; ] 
[ qty = pp. value * 1.0; ] 
[ value = qty; ] 
[ rate = pp. rate; ] 

4.1 .3.6.1 Associated Actions 

The following default actions are invoked from the linejrate control: 

■ Select 

■ Menu 



4-1 6 RHYTHM SCP Customization Manual 



March 27, 1998 © 1998 12 Technologies, Inc. Proprietary Information 



Applying Controls, Formats, and Styles 



Controls 



AAA list bar 



The list_bar control is a bar_chart control that is displayed within a 
bar_chart layout. A cell displayed with a listjbar control is expected to 
contain a list of values. All values in the list are stacked to form a single 
bar within the chart. 

The data for list_bar comes across in a vector of values. Since there is 
only one control, things such as bar color are had to determine. Bar_color 
and tool_tip legend are determined as follows: 

■ If a bar_color property exists, then it is parsed and stored in a vector 
of colors. For example, 

[axis: time^buckets (time, res_name) ; ] 
[ 1 is t_bar (capacity, product); property: bar^color = 
"blue, red"; ] 

This is different from the bar control in that it takes a comma-delim- 
ited list of colors 1-to-l with the number of parameters in the listjbar 
signature. So, capacity shall be blue and product shall be red. These 
bars shall be stacked upon one another for each resource in each time 
bucket. If only one color is specified, then all bars in the listjbar get 
that color. If no color is specified as a property, then the default is used 
(black). 

■ The tooljtip string is derived from the title__attribute of the axis chart 
element of the chart_value. Only one of title_attribute exists and it 
happens to be the first bar's title. Therefore, from the example above 
for bar_color, the tool_tip for capacity and product reads "Capacity". 
However, the user can create a legend layout under the bar chart lay- 
out to explain the bar contents. 



The following default actions are invoked from the list_bar control: 

■ Select 

■ Menu 



4.1.4.0.1 Associated Actions 
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4.1.4.1 map_connect 

map_connect is a map_chart control used to connect different nodes 
within a map chart. map_connect only appears within the context of a 
map_chart layout. The control expression for rnap_connect might be the 
following: 

[ Al = unique_id; control: map_connect; action: ; ] 

The map_connect control might appear in a map chart named 
bom_buf_buf_connects.lyt. The layout file bomJbuf_connects.lyt and its 
corresponding worksheet file are shown below. 

// Layout: 

axis_cross bom_buf_buf_connects 
{ 

worksheet : bom_buf_buf _connects ; 
sparse: false; 

Y: A3 A2 C2 Dl D2 El; 
[ A3 - control : map_connect ; ] 

} 

/ /Worksheet : 

replicating bom_buf _buf ^connects (Item item) 
{ 

height : 3 ; 
width : 4 ; 

[ Al buffer = item.buf f ers ; ] 

[ A4 = recurse (buf f er , f or_each ( # . pr oduc ing_oper a t i on 



. all_consume_f lows , # .buffers) ) 

. filter (#.flow_policy != "INFINITE"; ] 



[ 


A4 


.title = "A4" ; ] 




[ 


CI 


= f or_each ( A4 .producing^ 


operation . al l_consume_f lows , 






#. buffer); ] 




[ 


CI 


.title = "From Buffer"; 


] 


[ 


Dl 


= do(A4, 2) ; ] 




[ 


Dl 


-title = "Arrow"; ] 




[ 


D2 


. = "solid"; ] 




[ 


D2 


.title = "dashes"; ] 




[ 


El 


= do(A4, "Yellow"); ] 




[ 


El 


.title = "Color"; ] 




[ 


A2 


= A4.id; ] 




[ 


A2 


-title = "To Buffer ID" ; 


] 


[ 


C2 


= CI. id; ] 




[ 


C2 


-title = "From Buffer ID 


"; 3 


[ 


A3 


= CI . current„index + 1; 


] 


[ 


A3 


. title = "A3"; ] 





} 
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4.1 .4.1 .1 Associated Actions 

The following default actions are invoked from the map_connect control: 

■ Select 

■ Menu 
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4.1 .4.2 map_node 

mapjfiode is a rnap_chart control used to display different nodes within a 
map chart. map_node only appears within the context of a map_chart lay- 
out. The control expression for map_node might be as follows: 

[ Al = unique_id; control: map_node; action: ; ] 

The map_node control may appear in a map chart named 
bom_bujfer_nodes.lyt. The layout file bom_buffer_nodes,lyt and its cor- 
responding worksheet file are shown below. 

/ /Layout 

axis_cross bom_buf f er_nodes 
{ 

worksheet : bom_buffer_nodes ; 
Y: Bl CI Dl El Fl Gl Kl Jl Ml H4 ; 
[ Bl - control: map node ; action: drag - 

display_report ( "buff er_edi tor " , Al) ; 
action : MENU = echo ( "control menu : " ) ; 

action: dblclick = display^report ( "buf f er_map" , Al ) ; 
action: select =0; ] 

} 

/ /Worksheet : 

replicating bom_buf f er_nodes (Item item) 
{ 

height: 1; 
width: 11; 

[ Al buffer = item. buf f ers ; ] 

[ A2 = recurse (buffer, for_each (# .producing_operation 

. all„consume_f lows , #.buffers)); ] 
[ A2. title = "Buffer"; ] 
[ Bl - A2.id; ] 
[ Bl. title = "id"; ] 
[ CI = A2 . location. id; ] 
[ CI. title = "Parent ID"; ] 
[ Dl = do(Al, 8.0; ] 
[ Dl. title = "x"; ] 
[ El = 10.0; ] 
[ El .title = "y" ; ] 
[ Fl = do(Al, 4.0); ] 
. [ Fl . title = "w" ; ] 
[ Gl = do (Al, 4.0); ] 
[ Gl . title = "h" ; ] 
[ HI - item. owner . owner ; ] 

[ H2 = HI .plans . find ( "Abrasives Actual Plan"); ] 
[ H3 = H2 . si te_plans . find ( item. owner ) ; ] 
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[ H4 = H3 .buf fer_plans . find(A2) .on_hand(H3 .owner 

. horizon. start) . number) *0 . 01 ; ] 
[ HI. title = "Qtyl"; ] 
[ Jl = "triangle, Buf fer" ; ] 
[ Jl. title = "Shape"; ] 
[ Kl = left <A2 .name, 16); ] 
[ Kl. title = "label"; ] 
[ Ml = "Magenta, Buffer"; ] 
[ Ml. title = "Color"; ] 



The following default actions are invoked from the map_node control: 

■ Select 

■ Menu 



4.1 .4.2.1 Associated Actions 
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4.1.4.3 time buckets 

The timejbuckets control is a bar_chart control which specifies the cell val- 
ues used to label the x axis. The timejbuckets control is always used in con- 
junction with the axis property. The control expression for timejbuckets 
might be as follows: 

[ axis: timejbuckets (B2 ) ; 3 

The timejbuckets control might appear in a bar_chart layout named 
revenue _costJbar_chart.lyt. The layout file revenue _costJbar _chari Jy n and 
its corresponding worksheet file are shown below: 

/ /Layout 

bar_chart revenue__cost_bar„chart 
worksheet: revenue_cost_bar_chart ; 

[ axis: time_buckets (B2 ) ; ] 

[ bar(Fl); style: Barl; width: 30; ] 
[ bar(F2); style: Bar2 ; width: 40; ] 

/ /Worksheet 

replicating revenue_cost_bar„chart (Plan plan, 

List [Date_Range] bucket_list) 

[ head = "Revenue-Cost Bar Chart"; ]; 

[ Bl dates - bucket_l is t ; ] ; 
[ B2 dates = dates, start; ] ; 

[ Fl cost = plan. site plans. filter (#. si te . managed) 

. f or_each ( # . supply_request) 
. filter (within ( # . accepted, 
dates) ) . for_each 
(# . delivery_requests) 
. f or_each ( # . delivery__promise ) 
. f or_each ( #delivery_price) .sum; ] ; 

[ Fl. title - "Cost"; ]; 

[ F2 revenue = plan . site_plans . filter (#. site . managed) 

. for_each(# . supply^request) 
. f iter (within ( # . accepted, dates ) ) 
. f or_each ( # . delivery_reques ts ) 
. f or__each ( # . delivery_promise ) 
.for each ( #del ivery . price ) .sum; ] ; 

[ F2. title = "Revenue"; ]; 
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4.1 .5 Table Controls 

Table controls are controls used in table layouts. Table controls can only 
be used in table layouts. They are as follows: 

■ percentage _bar 

4.1.5.1 percentage_bar 

percentage _bar is a table control which displays a small graphic to repre- 
sent the numeric value of the cell. Cell values which display using this 
control are expected to range from 0 to 100. 

4.1.5.1.1 Associated Actions 

The following default actions are invoked from the percentage _bar con- 
trol: 



■ Select 



■ Menu 
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4.1.6 Text Controls 

Text controls can be used in almost all layouts. Many text controls allow 
text to be inserted. Others restrict what can be typed or may invoke vali- 
dation rules on the contents. Others are uneditable. The following con- 
trols are categorized as text controls: 

■ button 

m checkbox 

■ combo _popdown 

■ general 

m image_control 

■ indented_general 

■ label 

■ layout 

m menu Jit em 

■ menu_radio_item 
m outline ^general 
m radiojbutton 

■ separator 

■ slider 

■ spinner 

■ submenu 

m tooljbutton 

■ update _tool_button 
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4.1.6.1 



button 



A button control displays as a button with a label that is associated with 
an action when selected. The control expression for the leftmost button 
would be the following: 

[Al = "Gantt Chart"; style: Button_Bar; control: button; ] 

The first parameter in the expression is the label for the button. 

The entire set of button controls might appear in an axis_cross layout 
named menu_buttons.lyt. The layout file menujbuttons.lyt and its corre- 
sponding worksheet file are shown below. 

axis_cross menu_buttons ( ) 
worksheet ( ) 

[Al = "Gantt Chart"; style: Button_Bar; control: button; 
action: select = do ( show ( "res_gantt_chart " ) , 
hide ( n res_chartl " ) , hide ( "res_chart2 " ) ) ; ] ; 
[ A2 = "Actual Load"; style: Buttonjar; control: button; 
action: select = do ( hide ( "res_gantt__chart " ) , 
show( "res„chartl") , hide ( "res_chart2 " ) ) ; ] • 
[ A3 = M Std Load"; style: Button_Bar; control: button; 
action: select = do ( hide ( "res_gantt_chart" ) , 
hide("res_chartl") , show ( "res_chart2 " ) ) ; ] ; 
[ A4 = "All Charts"; style: Button_Bar; control: buttons- 
action: select = do ( show ( M res_gantt_chart " ) , 
show( "res_chartl" ) , show ( w res_chart2 " ) ) ; ] ; 
[ A5 = "Hide All"; style: Button_Bar; control: button; 
action: select - do ( hide ( "res_gantt_chart" ) , 
hide( "res_chartl") , hide ( n res_chart2 " ) ) ; ] ; 
y: al, a2 , a3 , a4, a5'; 
de f au 1 throws : 1 ; 
visible: true; 
no_scroll: true; 
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4.1.6.1.1 Parameters 

An alternate button control may be implemented for use in toolbars by 
using the following expression: 

button (String image_name, bool vertical_p, 
bool center p) ; 

The button label, if any, comes from the cell value. 



Table 8: Parameters 







image_name 


One of the defined images in FIGURE 22. 


vertical_p 


When true, this parameter means to place 
the label below the icon, else the label is to 
the right of the image. 


center_p 


When true, the parameter means the icon 
and label should be centered in both 
dimensions within the space available. 



FIGURE 22 Visual Resource Buttons 
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4.1.6.1.2 Associated Actions 

The following default action is invoked from the button control: 

■ Select 
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4.1.6.2 checkbox 



A checkbox control displays as a two-state toggle. There are three ways 
in which a control can be written, each format affecting the way the title 
of the checkbox displays. The control expressions for checkbox are as fol- 
lows: 

■ checkbox ( ) - takes the title string from the default logical specifica- 
tion, and changes it to match the current toggle state. The default logi- 
cal specification is found in the format file. 

■ checkbox (String) - uses String in double quotes as the checkbox title. 
Specify ( " ") if a title is not to be displayed. 

■ checkbox ( String , String) - uses String, String as true and false title 
strings, which change to match the current toggle state. String, String 
is positional; the first text string is for true, and the second is for false. 
When the toggle is depressed (true), then the first String is displayed. 
When the toggle is not depressed (false), then the second String is dis- 
played. 



A checkbox automatically confirms (completes the edit by sending to the 
engine) when the control is selected by the mouse. That is, the following 
expression does not need to be added to every checkbox to get it to react 
more than just visually to the button push: 

action: select = dispatch ( "confirm" ) 



4.1.6.2.1 Confirm 
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The checkbox control might appear in a spreadsheet layout named 
style _colors.lyt. The layout file style _colors.lyt and its corresponding 
worksheet file are shown below. 

spreadsheet sed_colors ( style) 

worksheet (Style style) 

[Al = "Invert?"; Style: Row_Title; Width: 170;]; 
[Bl = style . invert ; control: checkbox ( ) ; 
[CI = style . proper ty_defined (" invert ") ; 
control: checkbox () ; Width: 85; 

[A2 = "Foreground"; Style: Row_Title; Width: 170;]; 
[B2 = style. foreground_color; Width: 170;]; 
action: report = set_cell (get_color (gui„string 
("relative", 0, 0)));]; 
[C2 = style .proper ty_defined ( w f oreground_color ") ; 
control: checkbox ( ) ; Width: 85;] 

[A3 - "Background"; Style: Row_Title; Width: 170;]; 
[B3 = style .background_color; Width: 170;]; 

action: report = set^cell (get_color (gui_string 
("relative", 0, 0)));]; 
[C3 = style . property_def ined( w background_color" ) ; 

control : checkbox ( ) ; Width: 8 5 ; ] 



The following actions can be invoked from the checkbox control. Note 
that the functionality attached with these actions is not typical of the 
checkbox control. Note also that the confirm action OR the select action 
can be specified, but not both. 

■ Confirm 

■ Select 



4.1.6.2.2 Associated Actions 
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4.1.6.3 combo_popdown 

A combo _popdown displays as a combo-box with a default value, and a 
pop-down list of alternatives. The control expression for this 
combo _popdown would be as follows: 

[ A2 = vars . kind; control: combo pop down ] 

When the down-arrow is pressed, the options of VARIABLE and CON- 
STANT are visible. VARIABLE is the default, as defined by OIL for the 
basic type of Variable_Kind. 

4.1.6.3.1 Confirm 

The combo _popdown automatically confirms (completes the edit by 
sending to the engine) when the control is selected by the mouse. That is, 
when an item is selected from a combo's menu, it is not necessary to 
press <Return> for the change to take effect. 

The combo _popdown control might appear in an axis_cross layout 

named site _plan_editor.lyt, with the popdown consisting of options 

LINK, SUPPLIER, and CUSTOMER. The layout file 

site jplan_editordyt and its corresponding worksheet file are shown 

below. 

axis_cross site_plan_edi tor 

worksheet: site _jplan_editor 
Y: Fl Gl Dl 

[ Fl = control : corcibo popdown; ] 

[ Gl = control : checkbox; ] 

[ Dl = action: report = dispatch ( w model_edit ") ; ] 
/ /Worksheet 

replicating si te_plan_edi tor (Site_Plan site_plan) 
t Bl site = si tejtlan . site ; ] 

[ CI plan_description = site_plan . description ; ] 

[ C2 site_description = site_plan . si te . description; ] 

[ Dl - site ..plan . organization plan; ] 

t El plan = site plan. owner; ] 

[ Fl = site. role; ] 

[ Gl = site .managed; ] 



This layout with the combo _popdown control is shown when the Supply 
Chain Editor button control is selected. 
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4.1.6.3.2 Layout 

All layouts used in a report must be named as a layout in the .rpt file. 
Therefore, even if the layout for the combo _popdown does not appear 
directly on the report, but is contained within another layout of the report, 
it must be listed in the .rpt file. The following code fragments illustrate 
this more completely. 

//file my_report . rpt 

my_report ( . . . some parameters . . . ) 

{ 

layout: layout_that„actually_shows_in_the_report ( ) ; 
layout : nonphysical_datatable_types ( ) ; 

} 

//file layout_that_actually_shows_in_the_report . lyt 
spreadsheet layout_that_actually_shows_in_the_report 
{ 

worksheet : layout_that_actually_shows_in_the_report 

[ E4 - control : combo popdown 

( u nonphysical_datatable_types" , TRUE); ] 

} 

//file layout_that_actually_shows_in_the_report.wrk 
normal layout_that_actually_shows_in_the_report ( ) 
{ 

[ E4 = values { "Data_Table_type_Enum" ) 

. filter (#! = "PHYSICAL" ) . first; ] 
//the line above computes an initial value for the 
combo_box 

} 

//file nonphysical_datatable_types . lyt 
axis_cross nonphysical_datatable__types 
{ 

worksheet : nonphysical_datatable_types ; 
sort: Al; 
y: Al; 

> 
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/ / file nonphysical_datatable_types . wrk 
replicating nonphysical_datatable_types ( ) 
{ 

[ Al = values ( "Da ta_Tabl e_type_Enum" ) 

. filter (#! = "PHYSICAL"); ] 
[ Al. title = w "; ] 

} 



The following actions can be invoked from the combo _popdown control. 
Note that the functionality attached with these actions is not typical of the 
combo _popdown control. Note also that the confirm action OR the select 
action can be specified but not both. 

■ Confirm 



4.1.6.3.3 Associated Actions 



■ Select 
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4.1 .6.4 general 

general is a control that displays as a string. It is typically used in format- 
ting the date and time styles within a layout. If the cell containing the 
control has a command whose name matches an icon name, then the icon 
is displayed to the right of the string. Clicking on the icon invokes the 
command. Common icon/actions are as follows: 

■ combo_popdown choices 

■ toggle-through menu choices 

■ including more information on a report 

■ Report buttons which open the report that is the next logical in the 
flow 

The control expression for a general control would be the following: 

[ Cl - control: general ( "short" ) ; ] 

Note: For spreadsheet and axis cross layouts, the default control is gen- 
eral. If the user does not specify otherwise, the general control is auto- 
matically set for that cell. 
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The general control may appear in a layout named 

active _problem_lisLlyt. The layout file active _problem_listlyt and its 

corresponding worksheet file are shown below. 



/ /Layout : 
// 

axis_cross ac ti ve_pr oblem_l i s t 
{ 

worksheet : active_problem_list ; 
sort: CI; 
sparse: false; 

Y: LI A2 CI Dl El Fl ("Zl" Gl HI II Jl Kl K2 ) Ml ; 
CI = control: general ("short") ; ] 

Fl = action: more = display_report ( "more" , Fl & 

" Problem" , A3 ) ; ] 
Gl = action: report = dispatch ( "model_edit" ) 
HI = action: report = dispatch ( "model_edit" ) 
II - action: report = dispatch ( "modelled! t" ) ; ]/ 
Jl ~ action: report = dispatch ( w model_edi t " ) 
Kl = action: report = dispatch ( "model_edit" ) 
K2 = action: report = dispatch ( "modelled! t " ) 
Gl. title = style: Row^Title; 
Hl. title = style: Row_Title; 
II. title = style: Row_Title; 
Jl. title = style: Row_Title; 
Kl. title = style: Row_Title; 
K2. title = style: Row_Title; 
Ll = control : button ( ) ; 

action: select = A3 . resolve (Al . owner ) ; ] 
A3 = action: report = dispatch ( 11 model_edit ") ; ] 
Ml = protected: true; ] 
} 
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/ /Worksheet 
// 

replicating active_problem_list (List [ Active_Problem] 

active_problems ) 

{ 



Al a_problem = active_problems ; 
Al. title = "Problems"; 3 
A2 - a_problem. focus ; ] 
A3 problem = a_pr obi em. problem; 
Bl - problem. description; ] 
CI - problem. dates ; ] 
CI. title = "Plan Dates"; ] 
Dl = problem. cos t ; ] 
El = problem. interaction ; ] 
Fl = problem. category ; ] 
Gl = problem. resource_plan; ] 
HI = problem, buf f er_j?lan ; ] 
II = problem. operation__p lan; ] 
II. title = "Operation Plan"; ] 
Jl = problem. operation . state; ] 
Kl = problem. request ; ] 
K2 = problem. it em_request; ] 
LI = do (problem, "Resolve"); ] 
LI. title = ""; ] 
Ml = problem. las t„change ; ] 
Ml. title = "Detected"; ] 
Zl = ""; ] 
Zl. title = "Details"; ] 



] 



} 



4.1.6.4.1 Associated Actions 

The following actions can be invoked from the general control. Note that 
the functionality attached with these actions is not typical of the general 
control. 

■ Choose 

■ Confirm (only if the cell is editable) 

■ Map 

■ Menu 

■ More 

■ Report 

■ Select 
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4.1 .6.5 image_general 

imag e_general (image„gener a 1 (String, String, Integer )) dis- 
plays as a string and an image (icon). Unlike using the general control, 
the image _general control cell will NOT draw an icon to the right of the 
string if the cell containing the control has a command whose name 
matches an icon name. Instead, the second string parameter is the name of 
an image. This image shall be drawn next to the string. The third parame- 
ter controls the placement of the image: 0=Left, l=Right, 2=Top, 3-Bot- 
tom. In all cases, the image and text will be centered with respect to one 
another. 

The control expression for image ^general is: 

[ B2 = control: image_general ( "default" , "scp„logo", 0); ] 

The image _general control appears in the layout named main_header.lyt. 
This layout file and its corresponding worksheet file are shown below: 

// Layout: 

spreadsheet main_header 
{ 

worksheet: main_header ; 
style: Button ; 

action: show_report - domains . find (domain) . activities 

. find (activity ) .display; 
action: ok = dispatch (" show_report ") ; 
[ Al = width: 5; height: 10; ] 

[ B2 = control: image_general ( "default " , "scp_logo" , 0); ] 
[ C2 = width: 60; ] 

[ D2 = control: button ( ) ; top_inset: 15; bottom_inset : 15; 

action: select = dispatch (" show_report ") ; ] 
[ E2 = width: 140; ] 

[ F2 = control: image_general ( " default , " i2_small " , 0); ] 
[ G3 = width: 5; height: 10; ] 

} 

// Worksheet: 

normal main_header (String domain, String activity, 

String io) 

{ 

[ Al = " " ; ] 
[ B2 = " " ; ] 
[ C2 = ""; ] 

[ D2 = " Display Report " ; } 

[ E2 = » " ; ] 
[ F2 = " " ; ] 
[ G3 = ""; ] 

} 
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4.1.6.6 indented_general 

indented_general is a control used to create a list which is indented by its 
depth. The notion of depth in a list arises from the use of the recurse 
function. The recurse function assigns depth based on the depth of the 
recursion. The difference between indented _general and outline ^general 
is that outline _general has connectors between items in the list. The con- 
trol expression would be as follows: 

[ Bl = control: indented_general ( M " , 18); ] 

The indented_general control might appear in a layout named 
product J'orecasts.lyt. The layout file product_Jorecastsdyt and its corre- 
sponding worksheet file are shown below: 

/ /Layout : 
// 

axis_cross product_f ore'casts 

i " > 

worksheet: sub__f orecas ts ; 

X : C2 ; 

Y: Bl CROSS; 
CROSS: E3 E4 E6 E8 



[ Bl 
[ B3 
[ CI 
[ C2 
} 



control 
control 
control 
control 



indent ed_general ( w " , 18); ] 
checkbox ( ) ; ] 
general ( "short " ) ; ] 
general ( w short ") ; ] 



4.1.6.6.1 Associated Actions 

The following actions can be invoked from the indented_general control. 
Note: The functionality attached with these actions is not typical of the 
indented_general control. 

■ Choose 

■ Map 

■ Menu 

■ More 

■ Report 
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4.1 .6.7 label 

label is a control used as a string that cannot receive focus. Therefore, it 
can be used to show strings in reports that are not supposed to be edited. 
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4.1.6.8 layout 

The layout control displays a layout of any type within a cell. If the jc and 
y layout properties are not present, then the cells are sized and positioned 
automatically. Since this is true for layout controls, side-by-side place- 
ment can be obtained by putting the controls in adjacent cells in the par- 
ent spreadsheet. 

The control expression for the main_header layout would be as follows: 
[ Al = control: layout ( "main^header " ) ; ] 

The entire set of layout controls for the main report might appear in a lay- 
out named mainJbody.lyL The layout file mainjbody.lyt and its corre- 
sponding worksheet file are shown below. 

/ /Layout 

spreadsheet main_body 
worksheet: main_body ; 
style: Button; 
no_scroll: true; 

[ Al = control: layout ( "main__ti tie ") ; ] 

[ A2 = control: button ( " juggler^large" , true, true); 

action: select ^ . display_report ( w about_scp" ) ] 
[ Bl = control: layout ( "main_header" ) ,- ] 
[ B2 = control: layout ( "main_content" ) ; ] 

/ /Worksheet 
normal main_body ( ) 
] 



[ Al = 

[ Bl - 

[ A2 - 

[ B2 = 
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4.1.6.9 menu_item 

A menujtem control appears as an item in a menu, menu_bar, or sub- 
menu. It has actions associated with it that are invoked when the menu 
item is selected. The example below shows the Close menu_item control. 
This menu item exists in the cascaded submenu control of the File menu 
layout in the main menubar layout. The control expression for the Close 
menu_item would be as follows: 

[ El = control: menu_item( "close") ; ] 

The "close " in the above example references the command in the corre- 
sponding worksheet which specifies to Close the window. 

The menujitem control might appear in a menu layout named 
res_planjilejrnenu.lyt accessed by a submenu layout for a menubar lay- 
out named res _plan_Jile_menuJyt. The layout file 
res^>lanjjle_menu.lyt and its corresponding worksheet file are shown 
below. 

/ /Layout 

menu res _p 1 an_ma i n_menu 
worksheet : res plan main menu ; 

[ Al = control: menu_item ( " save_res_plan_main_menu ; ] 

[ Bl = control : menu_item 

( " imp o r t_r e s pi an_ma i n_menu " ) ; ] 

[ Dl = control: menu_item ( "update" ) ; ] 

t El = control: menu_item ( "close" ) ; ] 

//Worksheet 

normal res_plan_main_menu ( ) 
height: 1; 
width : 6 ; 

[ Al = "Save"; ] 

[ Bl = "Import Res„Plan_Main"; ] 
[ CI = "Export Res_Plan_Main" ; ] 
[ Dl = "Update Report"; ] 
[ El = "Close _Window A w" ; ] 

4.1 .6.9.1 Associated Actions 

There are no actions supported for the menujitem control. The associated 
action is specified through the argument list. 
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4.1.6.10 men u_radio_i tern 

menujradiojLtem is a control which displays as an exclusive menu toggle 
item, either in a menubar or a menu. Only one menu_radio_item may be 
selected within a set of such items bound by separators inside a menu. The 
menu__radio_item control indicates which item is chosen from the menu 
by displaying a checkmark next to that item. The control expression 
would be as follows: 

[ = "Whole Horizon" ; 

control : menu_radio_item( "horizon_bucket" ) ; ] ; 

The menu_radiojitem control appears in the layout buckets _menu.lyt for 
the example above. The layout file buckets _menu.lyt and its correspond- 
ing worksheet file are shown below. 

/ /Layout : 

menu buckets -menu 

{ 

worksheet : bucket s_menu ,- 

} 

/ /Worksheet : 

normal buckets„menu () 

{ 

[ = "Whole Horizon" /control : 
menu_radio_item( "horizon_bucket " ) ; 3 ; 

[ = "Quarters"; control: 
menu_radio_item( "quarter^buckets" ) ; ] ; 

[ = "Months"; control: 
menu_radio_item( M month_buckets" ) ; ] ; 

[ = "Weeks_months" ; control: 
menu_radio_item( "week_month_buckets " ) ; ] ; 

[ = "Weeks"; control: 
menu_radio_item( "week_buckets " ) ; ] ; 

[ = " Days -Weeks -Months " ,- 
control : 

menu_radio_item( "day_week_month_buckets " ) ; ] ; 

[ = "Custom"; control: 
menu_radio__item( "custom_buckets " ) ; ] ; 1 
} 

4.1.6.10.1 Associated Actions 

There are no actions supported for the menu_radio_Jtem control. The 
associated action is specified via the argument list. 
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4.1.6.11 outline_general 

outline general is a control which displays a list with collapse/expand 
indicators. It graphically portrays the tree structure and provides little 
boxes containing or on nodes with children to perform collapse/ 
expand functions. A left click toggles the expansion state. If currently 
collapsed, all immediate children are expanded. If currently expanded, all 
children are collapsed. A shift-left click always expands all children. 

There are two versions of this control: 

outline_general (String) 
outline_general (String, Integer) 

The outline _general( String, Integer) version of this control takes a maxi- 
mum initial recursion level parameter (Integer) which allows the user to 
control whether or not all entries are displayed in the expanded format. 
Otherwise, both versions of outline _general behave identically. The con- 
trol expression would be as follows: 

[ Al = control: outline_general ( "L" ) ; 

style: Value_Cell_Outline; 

action: report = dispatch ( "model_edi t " ) ; ] 

The outline ^general control might appear in a layout named 
site_plan_list.lyt. The layout file site _plan_list.lyt and its corresponding 
worksheet file are shown below: 

//Layout: 
// 

axis_cross site^?lan__list 
{ 

worksheet: site_plan_list ; 
Y: Al Fl B2; 

[ Al = control: outline_general ( " " ) ; style: 
Value_Cell_Outline; action: report = 
dispatch ( "model_edit " ) ; ] 
[ Fl = control: combo^popdown; ] 
[ B2 = control : checkbox ( ) ; ] 

} 
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/ /Worksheet : 
// 



replicating si te_plan_lis t (List [Site_Plan] site_plans) 



height : 2 ; 
width: 11; 

[ Al site_plan = si te_plans . recurse (# .members ) ; ] 
[ Bl site = site__plan . site ; ] 

t CI plan_description = site_plan . description; ] 

[ C2 site_description = site__plan . si te . description ; ] 

[ Dl = site_plan.organization_plan; } 

[ El plan = site_plan . owner ; ] 

[ Fl = site_plan . role; ] 

[ Gl = si te_plan. members ; ] 

[ HI = si te_plan . resource_plans ; 3 

[ II = site plans. buffer plans; ] 

[ Jl = si te__plan . operation_plans ; ] 

[ Kl = si te__plan . requests ; ] 

[ 01 = site_plan . operat ion_states ; ] 

[ LI - do (site_plan, " " ) ; ] 

[ Nl problem_count = do ( si te_plan, 0); ] 

[ B2 = site .managed; ] 



The following actions can be invoked from the outline _general control. 
Note: The functionality attached with these actions is not typical of the 
outline _general control. 

■ Choose 

■ Map 

■ Menu 

■ More 

■ Report 



{ 



} 



4.1 .6.1 1 .1 Associated Actions 
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4.1.6.12 radio button 

radio Jbutton is a control which displays as an exclusive toggle button 
with a title string. If the empty string is specified, no title strings will be 
displayed. Its initial state is taken from the value of the cell. One control 
expression would be as follows: 

[ E3 = control: radio_button ( " " ) ; J 

The radiojbutton control might appear in a layout named 
supply _chain_list.lyt. The layout file supply _chain_list.lyt and its corre- 
sponding worksheet file are shown below: 

//Layout : 

axis_cross supply_chain_list 
{ 

worksheet supply_chain Jist ; 
sort: Al El; 
Y: E3 Al El; 

[ E3 = control: radio_button ( w " ) ; ] 

[ Al = action: report = display_report 

( w supply_chain_editor" , supply_chain) ; ] 
[ El = action: map = display_report ( "plan_map" , El) ; 
action: report = display_report 
("plan_editor") , El); ] 

} 
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//Worksheet : 

replicating supply_chain„list (List [ Supply__Chain] 

supply_chains , Plan chosen_j?lan) 

{ 

[ Al supply_chain = supply__chains ; ] 

[ Al. title = "Supply Chains"; ] 

[ A2 = supply_chain .name; ] 

[ Bl = supply_chain . description; ] 

[ CI = supply__chain . sites ; ] 

[ C2 = "Sites (" & supply_chain . sites . count . string &")"; ] 

[ C2 . title - "Sites" ,- ] 

[ Dl = supply_chain . sellers ; ] 

[ D2 - "Sellers (" & supply_chain . sellers . count 

.string &") " ■ ] 
[ D2. title = "Sellers"; ] 
[ El plans = supply_chain . plans ; ] 

[ E2 = "Plans (" & supply_chain .plans . count . string &")"; ] 
[ E2 . title - "Plans"; ] 

[ E3 chosen = (chosen^plan == El) , = set„variable 

(chosen_plan, El) ; ] 

[ E3. title = ""; ] 

4.1 .6.1 2.1 Associated Actions 

The following action is invoked from the radio Jbutton control: 

■ Select (if the user sets a variable) 

The following action can be invoked from the radiojbutton control. Note: 
The functionality attached with this action is not typical of the radiojbutton 
control. 

■ Confirm 
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4.1.6.13 separator 

A separator control appears as a horizontal line in a menu or submenu. It 
breaks the menu or submenu up into sections. It allows you to organize a 
menu into logical sections. It also makes menus easier to use. You can 
put a separator line before a command such as Quit, making it less likely 
that the command is selected unintentionally. The separator line is not 
grayed, but it is not selectable. The control expression for a separator is 
as follows: 

[ El = control: menu_i tern ( n save„as " ) ; ] 

[ Fl = control: separator ( ) ; ] 

[ Gl = control: menu_i t em ( " import " ) ; ] 

Note: The separator between the Save As and Import menu items. 

The separator control might appear in a layout named 
editor Jrle_menu.lyt. The layout file editor _file_jnenu.lyt and its corre- 
sponding worksheet file are shown below. 

/ /Layout : 

menu editor_f ile_menu 
{ 

worksheet: edi tor_f ile_menu ; 
visible: FALSE; 



[ 


Al 




control : 


menu_i tern ( "Start ") ; ] 


[ 


Bl 




control : 


menu_item( "open" ) ; ] 


[ 


CI 




control : 


menu_i tern ( "revert " ) ; ] 


[ 


Dl 




control : 


separator ( ) ; ] 


[ 


El 




control : 


menu_i t em ( " o i l_t es t " ) ; ] 


[ 


Fl 




control : 


menu_item( "oil_commit" ) ; 


[ 


Gl 




control : 


menu_item( "oil_save_as" ) 


[ 


HI 




control : 


separator ( ) ; ] 


E 


Jl 




control : 


menu_i tern ( " exi t " ) ; ] 



} 
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/ /Worksheet : 

normal editor_f ile_menu () 
{ 

height : 1 ; 
width: 19; 

[ Al = "_New" ; ] 

[ Bl = "_Open"; ] 

[ CI = "_Revert"; ] 

[ Dl = « " ; ] ; 

[ El = "_Apply Changes ^m" ; ] 
[ Fl = "_Save Changes"; ] 
[ Gl = "_Save Changes As ..." ; ] 
[ HI = " " ; ] ; 

[ II = copy_cells ( w base_f ile_menu" ) ; ] 
t Jl = "Exit"; ] 



} 
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4.1.6.14 slider 

A slider control appears as a slider. The slider allows a user to select 
from a range of values. The user can slide the slider to change the under- 
lying value of the slider. The slider has a range of values that delimit its 
movement. 

To illustrate, consider the traditional text control in a cell that provides 
the traditional spreadsheet cell behavior of textually editing the value of 
the cell. That control can be replaced in a layout by a slider control (if the 
cell type is numeric). The slider gives a graphic handle that slides in a 
groove that is indexed with the range of possible values. The user can 
change the value by sliding the handle via interaction with a mouse (or 
other input device). 

The slider control might appear in a layout named active _goal_list.lyt. 
The layout file active _goal_list.lyt and its corresponding worksheet file 
are shown below: 

/ /Layout 

axis_cross active_goal_list 
worksheet: act i ve_goal_l i s t ; 
sort: El Bl; 
Y: El E2 Bl D2 Dl C2 ; 

[ E2 = control: slider (0, 1); ] 

[ Bl = control : combo_jpopdown ; ] 

[ C2. title = style: Row_Title; ] 

[ C3 . title = style: Row_Title; ] 

[ C4. title - style: Row_Title; ] 

[ C5. title - style: Row_Title; ] 

/ /Worksheet 

replicating active__goal_list (List [Active_Goal] goals) 

[ Al goal = goals; ] 

[ Al. title = "Goals"; ] 

[ Bl = goal . strategy_goal . goal ; ] 

[ C2 = goal . total_interaction; ] 

[ C3 = goal .problem_count; ] 

[ C4 = goal . total_lateness ; ] 

[ C5 - goal . total_shortness ; ] 

[ Dl - goal . ad just ed__value; ] 

[ D2 = goal . strategy_goal . adjusted_target ; ] 

[ El focus = do (goal . f ocus_value, percentage ( 1 )) ; ] 

[ E2 = focus; ] 

[ E2 .title = ""; ] 
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4.1.6.14.1 Associated Actions 

The following actions can be invoked from the slider control. Note that 
the functionality attached with these actions is not typical of the slider 
control. Note also that the confirm action OR the select action can be 
specified but not both. 



■ Confirm 

■ Select 



© 1998 i2 Technologies, Inc. Proprietary Information 



March 27, 1998 



RHYTHM SCP Customization Manual 4-49 





Controls 



Applying Controls, Formats, and Styles 



4.1.6.15 spinner 



The spinner control allows a user to select from a list of values. The user 
can click on arrow keys to select the next or previous value in the list. 
The spinner has a range of counters that delimit it movement. Each 
counter indicated a different item in the list. The spinner works by using 
the arrows on the spinner and by editing the number display box on the 
control and pressing the <Return> key. The following expressions 
present one way to implement a spinner. 

[ Dl ^control : spinner ( 1 , 1000000); ] 

The spinner returns the last accepted value not the string seen in the cell. 

The spinner control might appear in a layout named skilljist.lyt. The lay- 
out file skill_lisUyt and its corresponding worksheet file are shown 
below: 

/ /Layout 

axis_cross skill_list 

worksheet: skill_list; 
Y: Al El D2 CI ; 
sort: Al; 

[ Al = action: report = dispatch { "model_edit " ) ; ] 

[ El • = control: combo_popdown ; ] 

[ Dl = control: spinner ( 0 , 1000000 ) ; ] 
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/ /Worksheet 

replicating skill_list (List [Skill] skills) 
height: 2 ; 
width : 9 ; 



Al 


skill - 


skills; ] 


Al 


.title = 


"Skill"; ] 


Bl 


= skill 


. name ; ] 


Bl 


.title = 


"Name"; ] 


CI 


= skill 


.description; ] 


CI 


.title = 


"Description" ; ] 


Dl 


= skill 


.resources; ] 


Dl 


.title = 


"Dl"; ] 


El 


= skill 


.selection; ] 


El 


.title = 


"Selection" ; ] 


Fl 


= skill 


. loading_operations ; ] 


Fl 


.title = 


"Loading_Operat ions " ; 


Gl 


= skill 


. loading_buf f ers ; ] 


Gl . 


title = 


"Loading Buffers"; ] 


HI 


= skill 


. owner ; ] 


HI 


.title = 


"Site"; ] 


11 


= skill 


. owner . owner ; ] 


11 


.title = 


"Supply Chain" ; ] 



[ D2 resource_count = skill. resources . count ; ] 
[ F2 = skill . loading_operations . count . string & 

" loading operation" & if (skill 

. loading__operat ions . count == 1, ""."s"); ] 
[ F2. title = "Loading Operations"; ] 
[ G2 = skill . loading__buf f ers . count . string & 

"loading buffer" & if ( skill . loading_buff ers 

.count == 1, ""."s"_; ] 
[ G2. title - "Loading Buffers"; ] 
[ Zl = ""; ] 
[Zl. title = ""; ] 

4.1.6.15.1 Associated Actions 

The following actions can be invoked from the spinner control. Note: 
The functionality attached with these actions is not typical of the spinner 
control. Note also that the confirm action OR the select action can be 
specified but not both. 

■ Confirm 

■ Select 
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4.1.6.16 submenu 

A submenu control appears as a submenu of another menu. The example 
below shows the submenu control for the File entry in the menubar lay- 
out. It has one argument which is the name of another menu layout to use 
as the submenu, submenu is used to organize menus. For example, the 
Edit menu might contain the submenu OIL, which might have the Report, 
Layout, and Worksheet menu_items. The control expression for the File 
submenu might be as follows: 

[ Al - control: submenu ( "editor^f ile_menu" ) ; ] 

The submenu control that displays the menu of file and edit submenu 
items might appear in a menubar layout named full_sed_menubar Ay t. 
The layout file full_sed_menubar.lyt and its corresponding worksheet file 
are shown below. 

//Layout 

menubar f ull_sed_menubar () 
worksheet: f i 1 l_s ed_menubar ; 
s ty 1 e : Menubar ; 

[ Al = control: submenu (" edit or_f ile_menu" ) ; ] 
[ Bl - control: submenu ( "editor _edit_menu" ) ; ] 

//Worksheet 

normal f ull_sed_menubar () 
height: 1; 
width : 2 ; 

[ Al = "_File"; ] 

[ Bl = "_Edit"; ] 
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4.1.6.17 tool_button 

The tooljbutton control displays as a button with an icon and a label 
string. When pressed, the tooljbutton will dispatch the specified action to 
the current focus cell, tooljbutton controls can only occur within a tool- 
bar layout. The control expression for Close this Report tooljbutton 
would be as follows: 

[ Al = control: tooljbutton ( "close_report " , "close", 
*Close this Report"); ] 

The entire set of tooljbutton controls might appear in a toolbar layout 
named scp_planJoolbar.lyt. The layout file scp _plan_toolbar.lyt and its 
corresponding worksheet file are shown below. 

//Layout 

toolbar scp_plan_toolbar 
no_scroll: True; 

[ Al = control: tool_button ( "close_report " , "close", 

"Close this Report"); ]; 
[ Bl = control: tool_button( "freeze_report" , "freeze", 

"Freeze this Report -- No Updates"); ]; 
[ CI = control: tool_button( "update_report" f "update", 

"Update this Report") ; ] ; 
[ Dl = control: tooljbutton ( "update_all " , "update_all " , 

"Update All Reports"); ]; 
[ El = control: tool_button ( "print_report " , "print", 

"Print this Report"); ]; 
[ Fl = width: 8; ] ; 

/ /Worksheet 

normal scp_plan_toolbar ( ) 



[ Al = 
[ Bl = 
[ CI = 
[ Dl = 
[ El = 
[ Fl = 



4.1.6.17.1 Associated Actions 

There are no actions supported for the tooljbutton control. The associ- 
ated action is specified via the argument list. 
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4.1.6.18 update_tooLbutton 

The update jtooljbutton displays as a button with an icon and a label 
string. When pressed, this button dispatches the specified action to the cur- 
rent focus cell. The update _jool__button control can only occur within a 
toolbar layout. 

The update Jtooljbutton also has an extra image name used to indicate 
when a report needs to be updated. When a value is changed within the 
report, the update jtooljbutton turns yellow. The control expression for the 
update jtooljbutton is as follows: 

[Cl = control: update_tool_button( "update_report" , 

"update_needed" , "update", "Update this Report"); ]; 

The update jtooljbutton control appears in the layout named 

main _toolbar. lyt. The layout file and its corresponding worksheet file are 

shown below: 

/ /Layout : 

toolbar niain_toolbar 
{ 

worksheet: main_toolbar; 
no_scrol 1 : True ; 

[ Al = control: tool_button { "close_report" f "close", 

"Close this Report"); ]; 
[ Bl = control: tool_button{ "freeze_report" , "freeze", 

"Freeze this Report -- No Updates"); ]; 
[ Cl = control: update_tool_button ( "update_report " , 

"update needed", "update", "Update this Report"); ]; 
[ Dl = control: tool_button ( "update_all " , "update_all" , 

"Update All Reports"); ]; 
[ El = control: tool_button ( "pr int_report " , "print", 

"Print this Report"); ]; 
[ Fl = width: 8 ; ] ; 

[ Gl = control: tool_but ton ( "save" , "save", 

"Save the Rhythm SCP Model") ; ] ; 
[ HI = control: tool_but ton (" import " , "import", 

"Import External Data into Rhythm"); ]; 
[ II = control: tool_but ton ( "export" , "export", 

"Export Data from Rhythm"); ]; 
[ Jl = width: 8 ; ] ; 

t Kl = control: tool__button ( "cut " , "cut", "Cut"); ]>,■ 

[ bl = control: tool_button ( "copy " , "copy", "Copy"); ]; 

[ Ml = control: tool_button ( "paste" , "paste", 

" Pas te " ) ; ] ; 
[ Nl = width: 8 ; ] ; 
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[ Ol = control: tool_button ( "help 1 
"Help on Cell" ) ; ] ; 



help_on_cell " 



} 



/ /Worksheet 
normal main_toolbar ( ) 
Al = 
Bl = 
CI = " " 
Dl = "" 
El = " " 
Fl = "" 
Gl = w " 
HI = "" 
II - 
Jl - 
Kl = 
LI = «» 

Ml = " " 
Nl - "" 
Ol = "" 
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4.2 Formats 



Basic types (e.g. Integer) have formats associated with them. Formats 
specify how the values are expected to be structured on input and output, 
for instance, how many decimal places are to be displayed. Formats are 
specified in .fmt files. The specification syntax is shown below: 



where format and specification must be typed as shown and substitutions 
must be made for format _name Type &ndformat_specification. The file- 
name of the .fmt file is format _name_Type.fmt. 

4.2.1 Invoking Formats 

There are several methods of invoking formats. Models are usually for- 
matted according to the type of their key fields. Many controls (e.g. gen- 
eral) accept format_name as a parameter. If not given such a named 
format, each worksheet cell will look for the format named "default" cor- 
responding to the type of its value. For an example, refer to the following 
files located in the .../reports/basic directory: 

■ default __date. fmt (for type Date) 

■ default JtogicaLfmt (for type Logical) 

FIGURE 23 shows an example of using format to specify a special Num- 
ber format. 



format format_name Type 



{ 

specification: format_specification; 
{ 
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Formats 



FIGURE 23 



Format Example 



format in .fmt file 

format special Number { 

specification: n(####.00n) "special"; 
} 



Using format in a layout 

[ Al = control: general ( "special") ; ] 

If Al contains 456, it displays as 456.00special. If Al contains -1034, it 
displays as (10.34)speciaL 
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4.2.2 Available Formats 

The following is a list of all available formats: 



■ : ' -. -. ■ ■ ■.. ■ 




accounting_number 


"n(#, ##0.00n)"; 


accounting__quantity 


"n(#, ##0.00n) S3"; 


comma_number 


"n-#, ###.##"; 


comma quantity 


"N-#, ###.## S3"; 


dd_date 


"DD"; 


default_date 


"YY-MM-DD hh:mm"* 


default date ranee 


"YY-MM-DD hh:mm"; 
separator: " / "; 


default integer 


"%d": 


default_list 


element format" default 
delimiter: ; 
width: 100; 

truncatedjbrmat: "(+ {0} ...)"; 


defaultjogical 


"No, Yes, False=0, True=l, 0=0, 1=1"; 


default_number 




defaulLpercentage 


"n-##.##\"%\" "; 


default_quantity 


"n-##.## S3"; 


default_quantity_range 


"n-##.## S3"; 
separator: "<"; 


def ault_restricti on 


"YY-MM-DD hh:mm"; 


default_string 




default_time 




dmy_hms_date 


"DD-MM-YYYY hh:mm:ss"; 


fulljist 


width: 2000000; 


hm_date 


"hh:mm"; 
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hms_date 


"hh:mm:ss"; 


hms_time 


"hh:mm:ss"; 


mm_dd__y y _date 


"MM/DD/YY"; 


month^date 


"YY-MMM"; 


newline_list 


delimiter: "\n"; 
width: 99999; 


short_date 


"YY-MM-DD"; 


short_date_range 


"YY-MM-DD"; 
separator: " / "; 


short_percentage 


"n-##V'%\" 



4.2.3 Special Notes on Controls and Format 

There are a few items of special importance to mention regarding for- 
mats. They are listed below: 

■ Controls cannot be created using OIL 

■ Formats can be created using OIL, but the Reload Report Definitions 
menu option will not work (you must shut the engine down and 
restart). 
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4.3 Styles 

Styles can be used to control the appearance of the cells by modifying 
their: 

■ colors 

■ fonts 

■ borders 

Styles are specified in .sty files. The exact properties of a style that are 
applied depend on the control in which the style is used. The same styles 
can be used across many reports which ensures uniformity in the look 
and feel of reports. 

4.3.1 Syntax for Specifying Style 

Style requires a particular syntax within OIL. This syntax is shown 
below: 

cell__style style_name { 
<property: value> 
... } 

where cell_style must be typed as shown and substitutions must be made 
for style_name, property and value. See Title.sty for an example. 
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4.3.2 Invoking Styles 

Style can be used within the layout cell specification: 

[ cell„id = style: style_name; ] 

where style must be typed as shown and a substitution must be made for 
cell_id and style_name. This specifies a style for this layout cell only. It 
is also possible to specify a default style for an entire layout by adding a 
style declaration to the properties of the layout. For example, 

spreadsheet x 

{ ... 

style: style_name; 

} 

A layout cell's style will override the default style. (See plan_context.lyt 
for an example of the use of style.) 



4.3.3 Available Styles 

The following is a list of all available styles and their descriptions: 







foreground_color 


The name of the foreground color. 


background_color 


The name of the background color. 


format 


The format applied to the value string. 


border_color 


The name of the border color. 


pattern 


The name of the stipple pattern to use. 


pattern_color 


The name of the stipple pattern color to use. 


h_align 


The horizontal alignment type. 


v_align 


The vertical alignment type. 


invert 


The specification, if TRUE, to swap foreground and back- 
ground colors. 


font__family 


The font family, such as arial, or courier. 


font_style 


The font style, such as normal, italic, or bold. 
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font_size 


The font size. 


border_style 


The default border style. Possible values include: bare, 
single_line, double_line, widejine, dashjine, 

wiuc udMi iiiic, siid.LiiJw in, wiue siiduow in, snduow oui, 

and wide__shadow_out. 


hnrHpt* ton 

UUl Utl IUU 


me uorcier siyie ior Lne Lop line. 


hrvrHf*r i*i<rht 


i iic uuiucr atyie tor liic rigiii line. 


borderjeft 


The border style for the left line. 


border_bottom 


The border style for the bottom line. 


width 


The width of the cell area. 


height 


The height of the cell area. 


disable 


The specification to draw an item greyed-out and to ignore 
input events. 


hide 


The specification to make an item invisible. 


protected 


The specification, if TRUE, to make the control value uned- 
itable. 


modal 


The specification, if TRUE, to make the report modal. 
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4.3.4 Applying Conditional Styles 

The UI does not hard-code style names. Conditionally applicable styles 
have the keyword condition, as in the following example: 



The accepted values for condition are SELECTED, EDITABLE, and 
FOCUS. 

If a style file in your private reports area does not use the condition key- 
word, RHYTHM SCP will apply the style unconditionally to all cells. 

4.3.5 Special Notes on Styles 

There are a few items of special importance to mention regarding styles. 
They are listed below: 

■ Styles can be created using OIL, but the Reload Report Definitions 
menu option will not work (you must shut the engine down and 



■ Appendix C contains UI design guidelines for applying controls, 
styles, etc. 

■ Appendix E lists the built-in images provided by OIL for use as icons, 




restart). 



etc. 
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Section 5 


Using Events, Actions, and 




Bindings 



You are now going to learn to apply events, actions, and bindings to the 
basic report you learned to create in the first sections. 



5.1 Events 

A GUI event is basically a user gesture, such as clicking a mouse button 
or selecting a menu item. There are ways to associate any software 
behavior with any GUI event. This is done through the use of: 

■ actions 

■ key bindings 

■ dispatch function 

We do not usually refer to the GUI event itself. Instead, we tend to refer 
to the actions that are associated with the GUI events. 

5.1.1 Actions 

An action is a named expression. Actions are normally associated with 
events. For example, when an event happens, the action attached to the 
event is identified and the associated expression is evaluated. Actions can 
be defined in any of the components of a report, but they are generally 
invoked from layouts. 

Actions can be divided into four categories: Mouse Gesture, Menu Ges- 
ture, Window Gesture, and Shortcut. Below, each category is listed with 
its respective actions. 
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MOUSE GESTURE ACTIONS (for a right-handed mouse) 

■ select: single-click with the left mouse button 

■ dblclick: double-click with the left mouse button 

■ drag: press and hold with shift left mouse button (middle button on a 
three-button mouse) 

■ abandon: type the <Esc> key 

■ confirm: type the <Return> or <Enter> key 

MENU GESTURE ACTIONS 

These actions are all invoked by choosing the appropriate menu item or 
toolbar button. 

■ add_cell 

■ add_col 

■ add_row 

■ create_model_tag 

■ delete_model_tag 

■ display _model_tag 

■ left_right 

■ move - identifies when you request to balance the load in the bucket 
with the available capacity 

■ move_in - identifies when you request to balance the load in the 
bucket with the available capacity 

■ move_in_or_off - identifies when you request to balance the load in 
the bucket with the available capacity 

■ move_in_out - identifies when you request to balance the load in the 
bucket with the available capacity 

■ move_out - identifies when you request to balance the load in the 
bucket with the available capacity 

■ move_out_or_off - identifies when you request to balance the load in 
the bucket with the available capacity 

■ swap_down - identifies when you want to manually sort by moving 
the cell with focus one row down 

■ undo„to_mark 

■ update - identifies when you request that the report be refreshed with 
the latest information in the engine 
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WINDOW GESTURE ACTIONS 

These actions are invoked through normal window navigation (e.g. pick- 
ing a new tab). 

■ on Jayout_hide - identifies when a layout changes from being visible 
to invisible 

■ on_layout_show - identifies when a layout changes from being invisi- 
ble to visible 

■ bn_report_open 

■ on_report_close 

■ on_report_raise 

SHORTCUT ACTIONS 

These actions provide pre-determined buttons that should invoke the 
indicated behavior when pressed. 

■ report: provides a blue "drill down" icon that should display another 
report that is related in some way to the data shown in the cell 

■ choose: provides a "choose" icon that should offer a choice of values 
for this cell. This is usually done by dispatching the system-defined 
model _choose action. 

■ more: provides a "more" icon that should display further information 
about the cell value 

■ map: provides a "map chart" icon that should display the map chart for 
the cell value 
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5.1.1.1 Action Syntax 

To declare an action, the syntax is as follows: 



action: ac t i on^name = expression; 



where action must be typed as shown, and substitutions must be made for 
action_name and expression. The action_jiame can be anything. 
Although using one of the pre-defined names is permitted, it will cause 
that action to be re-defined. The expression can be any valid OIL expres- 
sion. Any action's expression can refer to the following: 

■ all model fields 

■ built-in functions 

■ data type conversions 

■ cell pointer format 

■ any enum constant (e.g. LINK) 

■ numbers 

■ "quoted" strings 

For actions defined in report files, expression can contain any of the fol- 
lowing values: 

■ parameters that were passed to this report 

■ any variables and computes defined in the report 

For actions defined in layout files, expression can contain any of the fol- 
lowing values: 

■ parameters that were passed to the associated worksheet 

■ any variables and computes defined in the worksheet 

■ the worksheet's cell names (e.g. CI 4) 

Actions can be declared within layout cells (as layout properties), or as 
report properties. System-defined actions are specified in application.rpt. 
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5.1.1.2 Action Lookup 

When a user triggers a GUI event, OIL will associate an action with that 
event, and then proceed to search for a usable action declaration. 
RHYTHM S CP finds an action declaration to use by searching for defini- 
tions in a bottom-up order, as illustrated in FIGURE 24. 



FIGURE 24 Action Lookup 

application, rpt 

V " 

report 

7 

layout 
layout cell 



5.1.1.3 Invoking Actions 

Most layout cells may have one or more actions specified for invocation. 
For example, 

[ Z3 - action: select = echo ( "hello" ) ; ]. 

declares that if cell Z3 is selected, then the OIL expression 
echo ( "hello" ) will be evaluated. 

In addition, actions can be directly invoked from OIL expressions by dis- 
patching. The dispatch function is useful for redirecting a mouse ges- 
ture to another action. For example, 

action : choose = dispatch ( "model^choose" ) ; 

declares that if the choose action is recognized, then OIL should look up 
the model_choose action and evaluate its associated OIL expression. 
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5.1.1.3.1 Example Action 

The following worksheet and layout files illustrate the use of actions. 




Layout cell CI will be rendered as a button; if pressed, it will echo the 
name of the supply _chain. Layout cell El has two short-cut actions: map 
will display a map chart report, report will display a plan editor. Clicking 
on the appropriate icon at El will display the corresponding report. 

5.1.1.4 Commonly Associated Actions and Controls 

There are actions which are normally associated with each control. 
Therefore, the report writer should have these in mind when designing a 
report. However, there are also actions that would be reasonable to attach 
to a control (would not surprise the user), but are not typically associated 
together. 

There are also cases where nothing is appropriate, or where one or more 
actions should be specified by the control's parameters instead of via a 
separate action definition. For example, a tooljbutton specifies its own 
select action. Table 9 lists all controls and actions that would normally be 
associated with them, and the actions that could reasonably be associated 
with them. 
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Table 9: Associated Actions and Controls 









bar 


select, menu 


* 


button 


select 




checkbox 


* 


confirm (OR select, not both) 


combo 


* 


confirm (OR select, not both) 


combo_popdown 


* 


confirm (OR select, not both) 


filler_bar 






gantt_axis 


NO ACTIONS SUPPORTED 




gantt_bar 


select, menu 


* 


general 


* 


menu, report, more, choose, 
map, select, (confirm if cell 
is editable) 


indented„general 




menu, report, more, choose, 
map 


label 






layout 


NO ACTIONS SUPPORTED 




line 


select, menu 


* 


line_rate 


select, menu 


* 


line_step 


select, menu 


* 


list_bar 


select, menu 




map_connect 


select, menu 


* 


map_node 


select, menu 


* 


men u_i tern 


ACTION IS A PARAMETER OF THIS CONTROL 


menu_radio_item 


ACTION IS A PARAMETER OF THIS CONTROL 


outline^general 


* 


menu, report, more, choose, 
map 
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wmmmimmmmmfmmMmmm 




percentage_bar 


select 


* 


radio_button 


select 


confirm 


separator 


NO ACTIONS SUPPORTED 




slider 


* 


confirm (OR select, not both) 


spinner 


* 


confirm (OR select, not both) 


submenu 


NO ACTIONS SUPPORTED 




time„buckets 


NO ACTIONS SUPPORTED 




tool_button 


ACTION IS A PARAMETER OF THIS CONTROL 
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5.1.2 Bindings 

Bindings map keyboard events to defined actions. For example, a key- 
board accelerator is a binding. 

Binding syntax is as follows: 

bind; keyboard combination = action; 

For example, 

application ( ) { 

action: close = close_this_report ( ) ; 

bind: command+c = close; // command + means "control" 

} 

In the example above, the binding command+c will cause the action 
close to be invoked when the user types <CtrlxC>. The action close will 
then invoke the OIL function close_this_report. 

5.1.2.1 Binding Lookup 

RHYTHM SCP knows which binding definition to use according to the 
binding lookup. OIL searches for definitions in a top-down order, as 
illustrated in FIGURE 25 . 



FIGURE 25 Binding Lookup 

application.rpt 

7 ~ 

report 

t 

layout 

V 

layout cell 



Thus, a locally defined keyboard accelerator will never override one that 
is defined in application.rpt. 
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section 6 Using Variables and Computes 



You are now going to learn how to apply variables and computes to the 
reports you have been learning how to build. Through the use of these 
declarations, you can add dimension to certain controls, such as 
combo _popdowns and radio ^buttons. 



6.1 Worksheet Evaluation 

A worksheet cell's set expressions are evaluated only when the cell is 
edited (e.g. typing, clicking a checkbox, etc.)- A worksheet cell's get 
expressions are re-evaluated when one of the following occurs: 

■ the worksheet is first created and initialized 

■ an input parameter changes value 

■ any cell's set expression is evaluated 

Efficiency hint: Many times the worksheets in a report share informa- 
tion. Try to put the shared information in the report and pass it to all the 
worksheets that need it, instead of re-computing the same things in each 
worksheet. 

6.1 .1 Variable and Compute Declarations - Overview 

Variables and computes are mechanisms for holding values without 
requiring a worksheet cell. Unlike cells, they are usually used as interme- 
diates and are often not visible within the UI. Unlike normal worksheet 
cells, they can hold values of the type List. Variables and computes are 
similar to parameters in that they are initialized when the worksheet/ 
report is instantiated. 

Syntax for variable and compute declarations is straightforward, as 
shown below: 

variable variable_name = expression; 
compute compute_name = expression; 

These declarations can be made in worksheets or in reports. Just as lay- 
outs have no parameters of their own, layouts do not declare their own 
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variables or computes. They can, however, access those of the corre- 
sponding worksheet. 

6.1.1.1 Variables 

Variables maintain the initial value, even if the initializing expression's 
value changes subsequently. Variables can only change via the 
set_yariable OIL function. For example, the syntax of set_yariable is: 

set_variable (variable_name, expression) 

The type of the variable is determined by the type of the value returned 
by the initializing expression. The type of the value assigned to a vari- 
able via set_yariable must match the type of the variable. For instance, if 
the initial variable returned a Number, the new variable value must also 
be an Number. (OIL will make automatic type conversions where possi- 
ble and appropriate, e.g., from Integer to Number,) 

6.1.1.1.1 Using Variables N 

Variables can be used for the following: 

■ Initializing parameters for component layouts 

■ Transferring information between worksheets 

For example, a report can use variables as shown below: 

resource _plan„editor (Resource_Plan rp) { 
variable my_plan = rp . owner . owner ; 
layout: LI (my_plan) ; // uses a worksheet "Wl" 
layout: L2 (my^plan); } // uses a worksheet 



The worksheets Wl and W2 use the same Plan Model, the one held in the 
report variable my _plan, as their incoming parameter. If one worksheet 
makes a change to my _plan, both see the change. 



W2 
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Another example of using variables is shown below. This example illus- 
trates a cell that is initialized before allowing users to change its value. 

normal bb (Buffer_Plan bp) { 

variable dd = bp . owner . owner . horizon . start ; 

// initial value of F2 



[ E2 = "Enter Dates"; ]; 
[ F2 = dd; ] ; 



} 

Note: The ^expression for F2 is set„variable, i.e. OIL treats [ F2 = 

dd; ] ; as [ F2 = dd, set_variable (dd,#); ];. This is because 

OIL will try to create a set expression by using a set_ function on the 
gefs outermost function, if the set_ function exists. By definition, the 
set_ function for a variable is set_variable. 

Therefore, when the contents of F2 are, for instance, interactively edited, 
what occurs is that the inputs (which are represented by #) are used to set 
the value of dd. This in turn changes the value of F2. 
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6.1.1.2 Computes 

Compute updates its value whenever the initializing expression's value 
changes. This happens whenever the worksheet/report is re-evaluated. 
Unlike variables, the set_variable expression cannot be used with com- 
pute. However, computes are similar to variables in that the type of the 
compute is determined by the type of the value returned by the expres- 
sion. 

6.1.1.2.1 Using Computes 

A compute can be used to represent a complex computation. The com- 
pute item can then be used whenever the result of that expression is 
needed. This will enable RHYTHM SCP to perform more efficiently. 
Since a compute is not a cell, its value can easily be hidden from the end- 
user. 

An example of using a compute is shown below: 

normal siteplanwork (Site_Plan sp) { 

compute x - . . .//some really messy expression 
that returns a List that you'd rather not 
calculate more often than absolutely 
necessary; 
[ E2 = x. first; ] ; 
[ E3 = x. element (2); ] ; 
[ E4 = x. element (3); ]; 

} 

Note: Cells £2, E3, and E4 are read-only cells because there is no 
set_list_element function that OIL can use to automatically create a set 
expression. 
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6.1 .1 .2.2 Putting It All Together 

Given the following OIL expression in a worksheet: 

variable var = supply_chains . first . 

sites . first ; 
variable other = supply__chains . element ( 2 ) . 

sites . first ; 
compute comp = var. name ; 
[ Al = comp, do (define (tmp, var), 

set_variable ( var , other), 

set_variable (other , tmp)); ] 

// set__expression swaps var and other 

assume the layout uses the default control, general, for cell A 7; therefore, 
Al displays as an editable text cell. Assume also that var = "love", other 
= "hope"; therefore comp - "love" and Al contains "love". 

Now, think through this as a computer would. The user types in cell A] 
and presses the <Return> key. The <Return> triggers the confirm action 
found in application.rpt, which calls the edit_cell function, which in turn 
invokes the set expression for the cell, var and other exchange values 
(note that the user's typed input is ignored since # is not used in the set 
expression), and the worksheet is re-evaluated, which means the follow- 
ing: 

■ comp is re-initialized 

■ the get expression for cell Al is evaluated 

At the end, var = "hope", other = "love", comp = "hope", mdAl dis- 
plays "hope". 
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6.1.1.3 make_type 

makejtype is an OIL function that returns a value with a specified type. 
makejype requires a specific syntax which is shown below: 

make_type (value, Type__Name) 

where makejtype must be typed as shown and substitutions must be 
made for value and Type_Name. In the example above, makejtype 
returns a value with the type Type_Name. 

Here is an example of using makejtype for a cell that needs a List whose 
contents are not yet known: 

normal bb (Buf f er_Plan bp) { 

variable dd = make_type (nonexistent, List [ Site] ) ; 

[ F2 = dd. first;]; // won't display until the List 
// has at least one member, via 
// set_variable (dd, . . .) ; 

} 

Here is another example of using makejtype: 

compute x = make_type ("False", Logical) ,- 

will initialize x to the logical value of false , whereas: 

compute x - "False" ; 
initializes x to the string value false. 
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6.1.2 Re-using Definitions 

Definitions to be used more than once may be collected into files and 
included in reports or worksheets using the ^include declaration: 

#include "filename"; 

Example applications of re-using definitions are listed below: 

■ Common variable definitions (in .var files) 

■ Common action definitions (in .act files) 

■ Standard menubar and toolbar definitions (usually in .mnu files) 
An example of using the ^include declaration is shown below: 

plan_editor (Resource_Plan rp) { 

#include "planning . mnu" ; 
#include "problems_filter .var" ,- 
# include "planning . act " ; 

where the Resource Plan Editor includes the planning. mnu, 
problems Jilter. var, and planning.act files. 

Note: The ^include <filename> expression acts the same as if each dec- 
laration in the file were simply typed into the report. In the example 
above, Mnclude planning.mnu acts the same as if each declaration in 
planning.mnu had been typed into the plan^editor report. Therefore, if 
the contents of planning.mnu are subsequently altered and 
reload_report_def initions is invoked, the plan_editor report will 
not see the changes until the plan_editor is also re-initialized. 
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section 7 Using Replicating Worksheets 



Up to this point, you have been learning about writing reports using nor- 
mal worksheets. Now, you are going to begin learning to use replicating 
worksheets. An important use of replicating worksheets is in the axis 
cross layout. This section will familiarize you with using replication and 
axis cross. 

7.1 Replicating Worksheets 

In a replicating worksheet, one or more cells in the worksheet evaluates 
to a list of values. The expression associated with the replicating cell 
operates on each element in the list of values. Conceptually, a replicating 
worksheet is like having a normal worksheet for every value of the repli- 
cating cell. For example, 

replicating sc ( Supply_Chain supply_chain) { 
[ Al site = supply_chain .sites ; ] 
[ A2 managed = site .managed; 3 

} 

where site is an alias for cell Al and managed is an alias for cell A2. 

Here, Al will have as many replicates as there are elements in the list 
supply„chain. sites. A2 will have as many replicates as Al has; each of 
A2's replicates calculates the managed field of one of the sites in Al. 

The number of replicates in a cell can potentially be quite larger. To see 
this, consider the following example worksheet: 

replicating stuff (Plan p) { 

t Al site_plan = p . si te_plans ; ] 

[ A2 request - site_plan. requests ; ] 

[ A3 dr = request . delivery_requests ; ] 

} 
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Suppose that the incoming parameter "p" has three site_plans, all of 
which are LINK. Suppose that one has five requests, and the other two 
have Severn requests each. Finally, suppose that all requests happen to 
have two delivery_requests. Then the number of replicates in each cell is: 

Cel 1 Repl iral-.ps 

Al 1 + 1+1 = 3 

A2 1*5+1*7+1*7= 19 

A3 1*5*2+1*7*2+1*7*2=38 

If, on the other hand, each site^plan has ten requests, then A3 would have 
sixty replicates. If we add a cell, A4, as below: 

[ A4 ir = dr.item_requests; ] 

and there are three item__requests for each delivery _request, then A4 
would have one hundred fourteen replicates. Clearly, as one traverses 
through the model hierarchy using replication it is possible to have cells 
with hundreds or thousands of replicates. 

Cells in replicating worksheets may be assigned a title specification. This 
is a convenient way to give a title to the list of values in the cell for use 
by layouts that support titles (e.g. axis cross). The example below illus- 
trates the use of the title specification: 

replicating sc ( Supply_Chain supply_chain) { 
[ Al site = supply__cha in. sites ; ] 
[ Al. title = "Site"; ] 
[ A2 managed = site .managed; ] 
[ A2. title = "Managed"; ] 

} 
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7.1.1 



7.1 .1 .1 



Types of Replication 

There are different types of replications which are supported by a repli- 
cating cell depending on the relationships between cells in the same 
worksheet: 

■ Independent 

■ Single Dependent 

■ Multiple Dependent 

Note that cyclical dependencies (e.g. cell Al's value depends on cell 
A2's value and cell A2's value depends on Al) are not allowed in repli- 
cating worksheets. Dependency graphs are useful in debugging cycles 
and other replication errors. 

Independent Replication 

In an independent replication, the cell expression generates a list of val- 
ues and is independent of any other replicating cell in the worksheet. For 
example, 

replicating sc ( Supply_Chain supply_chain) { 
[ Al site = supply_chain . sites ; ] 

} 

// Al is independent 

The dependency graph for this example would look like this: 



Al 
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7.1.1.2 Single Dependent Replication 

In a single dependent replication, the cell expression generates a value 
that depends on one other cell in the worksheet. Either of the cells can 
replicate. For example, 

replicating sc ( Supply_Chain supply_chain) { 
[ Al site = supply_chain . sites ; ] 
[ A2 name = site. name; ] 

} 

// A2 is single dependent on Al 

The dependency graph for this example would look like this: 



Any cell that appears in a get expression establishes a dependency, even 
if its value is ultimately not used to calculate the cell's value. In this 
example, Al is appearing in the get expression for A2, thereby creating 
the dependency. The dependency is there, even if we make the following 
nonsensical change: 

[ A2 name = if(Al == Al , "Hello", site. name); ] 



Al 



A2 
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As another example of single dependent replication, consider the follow- 
ing: 

replicating sc ( Supply_Chain supply_chain) { 
[ Al site = supply_chain . sites ; ] 
[ A2 name = site, name; ] 
[ A3 opn - site . operations ; ] 

} 

The dependency graph in this case would look as follows: 



Al 




A2 A3 



In this example, A2 and A3 are dependent on Al. A3 is also a nested rep- 
lication, because it generates a list for every replicated value of AL 

7.1 .1 .3 Multiple Dependent Replication 

In a multiple dependent replication, the cell expression generates a value 
that depends on more than one cell in the worksheet. For example, 

replicating site ( Supply_Chain sc, Site x) { 
[ Al plan = sc. plans; ] 
[ A2 site = x; ] 

[ A3 sp - plan . site_plans . filter (#. site != x) ; ] 
} 

The dependency graph for this example would look like the following: 



Al A2 plan site 




A3 sp 



where A3 is dependent on Al and A2. The value of A3 cannot be gener- 
ated without first generating the values for Al and A2. 
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7 A.I List Functions 

"List" functions create and manipulate lists of values. There are several 
"list" functions: 



• count 


* list_jndex 


• filter 


• first 


• for_each 


• last 


• sort 


• list 


• sort_stable 


• bucketize 


• sublist 


• bucket_list 


• unique 


• bucket_symbols 


• contains 


• keyed_list 


• found 


• keyed_element 


• element 


• keys 


• find 


• recurse 


• find_or_nonexistent 


• recurse_andjxim 


• find_or_create 


• integers 


• key 


• multi_key 


• multi_keyed_list 


• multi_keyed_element 


• keynames 


• key„values 


• multi__key_bucketize 


• multi_key_bucketize_element 


• bucket_list_by_date 


• bucket_list_by_key 


• current_depth 





"List" manipulation functions such asfor_each iterate over each element 
of the list. Other functions, such as do or define, are useful when com- 
bined with "list" functions. Syntax Note: The element in the list that is 
being operated on is represented by #. 
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7.1.2.1 count Function 

count determines the number of elements in a list. The list can be of any 
type. In the expression count (list (vail , val2 , va!3 ) ) , count 
returns 3 as the number of elements in the list. FIGURE 26 shows exam- 
ples of the count function: 



FIGURE 26 



count Function Example 



count (list (5, 10, 15)) //returns 3 

list ("a", tt b", "c", M") .count// returns 4 



7.1.2.2 list Function 

list creates a list of values. Each value in the list must have the same type. 
If any of the parameters is a list, the elements of that list are included 
directly into the list. The expression list (vail „ val2 , . . . , vain) 
makes a list containing the values vail, val2> vain. FIGURE 27 shows 
an example of the list function within an expression: 



FIGURE 27 



list Function Example 



list (3 , list (2, 4) ) 



The example above would create a list containing the values 5, 2, 4 (in 
that order). 
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7.1 .2.3 sublist Function 

sublist returns a portion of another list as specified by the two integer 
parameters. In the expression sublist (List [void] , integeri , 
integer2 ) , Integeri is the position of the starting element and Integeri 
is the number of elements. FIGURE 28 illustrates the use of sublist: 



FIGURE 28 



sublist Function Example 



list(l, 2, 3, 4, 

list(l, 2, 3, 4, 

list(l, 2, 3, 4, 

list(l, 2, 3, 4, 



5) .sublist (2, 2) 

5) .sublist (5, 2) 

5) .sublist (6, 10) 

5) .sublist (0, 3) 



returns {2, 

returns (5) 

returns ( ) 
error 



3) 




7.1.2.4 for_each Function 

for_each traverses a list applying Expression to each element and placing 
the result in a new list. The expression f or_each (List [Void] , 
Expression) exhibits proper syntax for Xhtfor_each function. FIGURE 
29 shows an example of using f or _each: 



FIGURE 29 



for_each Function Example 



list(20, 6) .for_each(# + 3) 



returns (23, 9) 
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7.1.2.5 filter Function 

filter traverses a list applying the logical Expression to each element. If 
the result is true, then the element is added to a new list. The expression 
filter (List [Void], Expression, Integer) exhibits proper syntax 
for the filter function. The Integer parameter is an optional count for the 
maximum size for the result (defaults to infinite). This parameter pro- 
vides a limit which stops the search through the list once it has found the 
specified number of elements. FIGURE 30 displays an example of the fil- 
ter function: 



The re curse function creates a result list from the input list of values, 
then evaluates Expression on each member, adding the results of the 
evaluation to the result list. Expression is an OIL expression that returns 
a list. The resulting list maintains depth information for the elements in 
the list, which can be used to intelligently indent displayed results. For 
example, starting with a single-level Bill of Materials, recurse can calcu- 
late the full BOM and preserve the depth information needed to show the 
indented BOM. FIGURE 31 shows an example of using the recurse func- 
tion. 



FIGURE 30 



filter Function Example 



r 




list(20, 6).filter{# == 3) returns (20) 




7.1.2.6 recurse Function 



FIGURE 31 



recurse Function Example 



r 



list (20, 6) . recurse (#. my_f actors ) 
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In FIGURE 31, my factors (which is an integer) returns a list of the fac- 
tors of its input integer. The result starts as (20, 6). Then 20 is passed to 
my Jactors, which returns (2, 4, 5, 10). The result is appended after 20: 
(20, 2, 4, 5, 10, 6). The list "knows" that 2, 4, 5, and 10 are "underneath" 
20. Next, 2 is processed, etc. The final result is (20, 2, 4, 2, 2, 5, 10, 2, 5, 
6, 2, 3). 

Note: The depth information is lost if the list generated by recurse is then 
operated upon by another list function such as filter. 

FIGURE 32 illustrates the correct way and the incorrect way to use the 
recurse function: 



FIGURE 32 



Correct and Incorrect Use of recurse 



replicating product^groups (List [Product_Group] 
product_groups) { 

[ Al right = product_groups . recurse (#. sub_groups 

. for_each (#. product ) group) ) ; ] 
[ A2 wrong = product„groups . recurse ( # . sub-groups ) 
. for_each ( # . product_group) ; ] 



In the example above, cell Al stores a hierarchical list of all the product 
groups under the input parameter list of product groups. Therefore, the 
depth information is preserved in A 1 because the for_each is performed 
while recurse is still being calculated. In contrast, A2 passes the result of 
recurse to for_each, which cannot preserve this information. 

7.1 .2.7 recurse_and_trim Function 

recurse _andjtrim behaves identically to the recurse function except that 
it has an additional boolean filter expression which is used to trim the 
resulting tree. The filter expression argument is a little different from the 
normal filter function because an element for which the expression 
returns false will still be included if one of its children's filter expressions 
returned true. In other words, this filter is specifically designed to trim 
dead branches of the tree. 

The correct syntax for the recurse _and_trim function is 

recurse_and_trim (List [Void], Expression, Expression). 
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7.1.2.8 sort Function 

The sort function orders a list based on the sorting expression. The 
expression sort (List [Void] , Expression) exhibits proper syntax 
for the sort function, sort processes a list until the sorting expression is 
true for all adjacent elements. (Note: Use V and 'b' as element place 
holders in the expression.) FIGURE 33 shows an example of using the 
sort function: 



FIGURE 33 



sort Function Example 



list(4, 6, 8, 2) .sort(a < b) 
returns list(2, 4, 6, 8) 



© 1998 i2 Technologies, Inc. Proprietary Information March 27, 1998 



RHYTHM SCP Customization Manual 7-1 1 




Replicating Worksheets Using Replicating Worksheets 



7.1.2.9 sort_stable Function 

sort_stable behaves identically to sort, except that sort_stable ensures 
that the ordering of the equal elements in the input list is maintained in 
the output list. sort_stable orders a list based on an expression. In con- 
trast, sort processes a list until the sorting expression is true for all adja- 
cent elements. The expression sort_stable ( List [Void] , 
Expression) illustrates the correct syntax for the sort_stable function. 
(Note: Use 'a' and 'b' as element place holders in the expression.) 

sort_stable is much slower than sort; therefore, use sort whenever possi- 
ble. FIGURE 34 shows several examples of using sort_stable: 



FIGURE 34 



sort_stable Function Example 



list(4, 6, 8, 2) . sort_stable(a<b) ; //returns list(2, 4, 6, 8) 

list("t", "h", "m").soit_stable(a>b) //returns list("t", "m'\ "h") 

list{25, 26, 17, 18, 19 ) . sort„stable ( integer (a/ 10 ) < integer (b/10 ) ) 
//This sorts by the most significant digit, and returns 
//list(17, 18, 19, 25,26) 

@~list(25, 26, 17, 18, 19) .sort (integer (a/10) < integer (b/10) ) ; 
//This sorts by the most significant digit, and returns 
//list(19, 17, 18, 26, 25) 

Notice that least- significant digits are in a different order. 



The following expressions are provided to illustrate the difference 
between sort_stable and sort: 



operations . sort (a . name < b . name ) . sort„stable 

(a. category < b. category); 



The expression above sorts operations using category as the primary key, 
and name as the secondary. The following does the same thing but is over 
twice as fast: 

operations . sort ( if (a. name != b.name, a. name < 
b . name , a. category < b . category )) ; 
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7.1.2.10 unique Function 

unique removes duplicate elements from a list, thereby returning a list of 
unique elements. The expression unique ( List [Void] ) shows the cor- 
rect syntax for unique. FIGURE 35 shows an example of using unique 
within an expression: 



FIGURE 35 



unique Function Example 



unique (list (1, 1, 3, 2, 1)); // returns list(l, 2, 3) 




7.1 .2.1 1 contains Function 

contains determines if a list contains a certain element. When given a list 
of models, contains searches using the Model's key field, but only 
returns TRUE if the matching key field model is the exact model instance 
given. FIGURE 36 illustrates the use of the contains function: 



FIGURE 36 



contains Function Example 



supply_chains , contains ( "test" ) ; / /returns TRUE if there is a supply chain 
//named "test in the list of supply chains 



list(l, 2, 3, 4) . contains (0) ;/ /returns FALSE 
contains (list (3 , 5, 7, 9), 7);// returns True 
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7.1.2.12 found Function 

found behaves identically to contains with the exception of its usage on 
models, found loosens the match criteria to merely key_fields (just like 
find, only found returns a Logical instead of the element), whereas con- 
tains matches the key field of the exact model instance. FIGURE 37 
below shows examples of the found function: 



FIGURE 37 



found Function Example 



supply_chains. found ("test") ; //returns TRUE if there is a supply chain 

//named "test" in the list of supply chains 

list(l, 2, 3, 4) .found (0) ///returns FALSE 
found (list (3 , 5, 6, 9), 7); //returns TRUE 



7.1.2.13 element Function 

element returns the requested element from a list. Passing 1 in as the sec- 
ond argument returns the first element in the list. The expression ele- 
ment (List [Void] , integer) illustrates the proper syntax for the 
element function. FIGURE 38 shows examples of using the element 
function: 



FIGURE 38 



element Function Example 



element (list (5, 10, 15), 1); 

listra", "b", *c" .element (2) ; 
list(l, 2, 3, 4) .element (5) ; 



//returns 5 

//returns "b" 
//returns an error 
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7.1.2.14 find Function 

find searches through a list of models and returns the first model whose 
key field matches the given value. This version of find is used when the 
first argument is a list of models. An error is returned if no match is 
found. The correct syntax for the find function is as follows: 

find (List [Void] ,Void) 
Examples of using Xhefind function are shown in FIGURE 39: 



FIGURE 39 



find Function Example 



supply_chains . find ( "test ");/ /returns the supply chain named "test 
sites . find ( "Dallas" ) ; / /returns the site named "Dallas" 




7.1.2.15 find_or_nonexistent Function 

find_or_nonexistent behaves identically to find by searching a list of 
models and returning the first model whose key field matches the given 
value. However, find_or_nonexistent returns nonexistent when no 
match is found. find_or_nonexistent is also used when the first argument 
is a list of models. 

FIGURE 40 shows two examples of the find _or ^nonexistent function: 



FIGURE 40 



find_or_nonexistent Function Example 



supply_chains . f ind_or_nonexi stent ( "test" ) ; 
//returns nonexistent 

site . find_or_nonexi stent { "Dallas" ) ; 

//returns the site named "Dallas" 
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7.1.2.16 fincLor_create Function 

find_or_create searches through a list of models and does one of the fol- 
lowing: 

■ returns the first model whose key field matches a value 

■ if the model does not exist, creates and appends it to the end of the list 
followed by returning the newly created model 

find_or_create is only available to a list of models. 

FIGURE 41 provides an example to differentiate between the 
find_or_create function and the fin d function. In this example, assume 
that the supply chain named "test" does not exist. Observe that the first 
expression yields an error because it did not find "test." The other expres- 
sions return the model named "test." 



FIGURE 41 



find_or_create Function Example 



r 




supply_chains 
supply_chains 



find ("test") ;/ /returns an error 
find_or_create ( "test" ) ; 

//creates and returns the model named w te 
f ind ( * test ");/ /returns the model 

//named "test" 
find_or_create ("test") ; 

//returns the model named "test" 



supply_chains 



supply_chains 
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7.1.2.17 list_index Function 

UstjLndex searches through a list of models and returns the position in the 
list of the first model whose key field matches the given value. It also 
searches an arbitrary list for a match (using the == operator). listjndex 
reports an error if the list element is not found. FIGURE 42 shows an 
example of using UstjLndex within an expression. It also provides an 
example illustrating the difference between listjndex and find: 



FIGURE 42 listjndex Function Example 



list ("a", "b", "c") .list_index("b") ; //returns 2 

some_list (some_list . list_index (key) ) ; 

is equivalent to... 

some_list . find (key ) ; 



7.1.2.18 first Function 

first searches through a list (of any type) and returns the first element 
within the list. If the list is empty, first returns nonexistent. The expres- 
sion first (List [Void] ) exhibits the correct syntax for the first func- 
tion. FIGURE 43 shows examples that illustrate the proper usage of the 
first function: 



FIGURE 43 first Function Example 



first(list (5, 10, 15)); //returns 5 

list ("one"/ "two", "three") . first; //returns "one' 
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7.1.2.19 last Function 

last searches through a list (of any type) and returns the last element of 
the list, last returns nonexistent if the list is empty. FIGURE 44 shows 
two examples of using the last function: 



FIGURE 44 last Function Example 



last(list(5, 10, 15)); //returns 15 

list (-one", "two", "three") . las t ;/ /returns "three' 




7.1.2.20 bucketize Function 

bucketize searches through a list and returns a list of values that are orga- 
nized by quick retrieval characteristics. Use bucketize when you want to 
be able to quickly retrieve values from a large list that is date-based in 
nature. The correct syntax for bucketize is shown below: 

bucketize (List [Void] , List [Date„Range] , 
Expression, Expression) 

bucketize organizes the input list into a table with one column per 
date„range (using the second parameter), and any number of rows 
(indexed by a symbol). The intersection (table entries) is a list which you 
can access using the bucket_list function. The last two parameters are 
used to determine which of the input items go into which symbol/ 
date_range intersection list. 

The following is a description of the workings of bucketize: 

1. First, bucketize takes the list of date_ranges, and makes a bucket for 
each one (Note that in a list of date_range buckets, any two adjacent 
buckets, A and B, must have: A.end == B. start) 

2. Then it loops over the list of values and does the following for each: 

• evaluates the date expression 

• finds the bucket in which that date expression fits (i.e. bucket.start 
<= date < bucket.end). (Note: this implies that given a bucket where 
bucket.start == bucket.end, nothing can ever fall within it) 

• evaluates the symbol expression 

• puts this value indexed by this symbol to the list in this bucket 
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7.1.2.20.1 Example Usage of bucketize 

Consider a list of item_promises. Put each one in the bucket whose 
date_range contains the given date as evaluated in the expression 
# . owner . due . start, and hash-keys it with the given Symbol as evalu- 
ated in the expression # . item . name. 

variable ips = delivery_promises . for^each 
(# . item -promises ) ; 

variable bl = bucketize (date_range_list , 
#. owner . due . start , #. item. name) ; 

The following is an extended user example. It is a contrived, non-model 
example, but it shows in painstaking detail the flow of data: 

define (date_range_list , list (date_range 
("95/01/01 00:00 / 95/01/02 00:00"), 

// bucket #1 
date_range( "95/01/02 00:00 / 95/01/06 
00 : 00" ) , // bucket#2 

date_range( "95/01/06 00:00 / 95/01/10 
00:00") , // bucket#3 

da t e_range ( "95/01/10 00:00 / 95/01/14 
00:00") , // bucket#4 

date_range("95/01/14 00:00 / 95/01/20 
00:00") ) ) // bucket#5 
define (b_example , integers ( 5 , 10 ) . 
bucketize (date_range_list , date ( "95/01/00 

00:00") + time (#. string & " day"), 

# . string) ) 

For the example above, we generate a date for each of the integer num- 
bers between 5 and 10 (specifically: "95/01/05 00:00", "95/01/06 00:00", 
"95/01/07 00:00", "95/01/08 00:00", "95/01/09 00:00", ""95/01/10 
00:00"). 

Therefore, integer 5's value gets stored in bucket#2 since: bucket#2. start 
<= (5's date) < bucket#2.end "95/01/02 00:00" <= "95/01/05 00:00" < 
"95/01/06 00:00". Integer 6 ends up in bucket#3 7 (NOT in bucket#2, due 
to the . Integers 7, 8 and 9 also get put in the list in bucket#3 as well. Inte- 
ger 10 ends up in bucket#4 (NOT in bucket#3, same reason as integer 6). 
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7.1.2.21 bucketjist Function 

bucketjiist is used to quickly retrieve a specific value (or values) from a 
list created by bucketize. bucketjiist finds the bucket whose given date 
falls within its date_range (i.e. bucket.start <= date < bucket.end). It then 
retrieves any values that were stored in that bucket with a lookup key that 
matches the given symbol. FIGURE 45 shows examples of using 
bucketjiist: 



b_example. bucke t__list (date ( "95/ 01 / 10 00:00"), "9") --> nothing 
b_example.bucket_list (date ("95/01/02 20:00"), "9") --> nothing 



The following examples of bucketjist show how the given lookup date 
does not have to match the original date used to put the data in that spe- 
cific bucket: 

b_example . bucket„lis t (date ( "95/01/02 20:00" ) , 

"5") --> 5 b_example.bucket_list (date 

("95/01/07 00:00"), "8") --> 8 
b_example . bucke t„l i s t (date ("95/01/06 00:00"), 

" 8 " ) --> 8 b_exampl e . bucke t_l i s t (date 

("95/01/06 00:00"), "9") 9 
b_example .bucke t_list (date ( "95/01/06 00:00") , 

"adam") --> nothing 

b_example.bucket_.list (date ( "95/01/09 23 :59") , 
"8") 8 



FIGURE 45 



bucketjist Function Example 



r 
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7 A. 2.22 bucket^sym bo Is Function 

bucket _symbols is used to get at the list of unique Symbols (keys) that 
were used in building the given list during bucketize. The expression 
bucket_symbols (List [Void] ) displays the correct syntax for the 
bucket_symbols function. FIGURE 46 provides an example of using 
bucke t_symbols : 



FIGURE 46 



bucket_symbols Function Example 



b_example .bucke t„symbols ( ) --> "5", "6", "7", "8", "9", "10" 




7 '.1. 2.23 keyed Jist Function 

keyed Jiist is used when you want to be able to quickly retrieve values 
from a large list. It loops over the list of values and does the following for 
each: 

■ Evaluates the symbol expression 

■ Stores this value, indexed by this symbol, in the new list 

The proper syntax for keyedjtist is shown below: 

keyed_list (List [Void] , Expression) 

FIGURE 47 shows examples of the keyedjtist function: 



FIGURE 47 



keyed Jist Function Example 



define (keyed, integers (1, 10 ). keyed_list (#. string & "0")); 

This expression stores the integer value 1 through 10 with the respective key-symb( 
of "10", "20", "30", "40", "50", "60", "70", "80", "90", "100" 
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7.1.2.24 keyed_element Function 

keyed_element is used to quickly retrieve a specific value (or values) 
from a list created by keyed [_list. The proper syntax for the 
keyed_element function is shown below: 

keyed_element (Symbol) 
FIGURE 48 provides examples of using the keyed_element function: 



FIGURE 48 



keyed_element Function Example 



keyed . keyed^element ( " 5 0 " ) - - > 5 
keyed. keyed_element ("5") --> nothing 




7.1.2.25 keys Function 

The keys function is used to retrieve the list of unique Symbols (keys) 
that were used in building the given list during keyed Jist. The correct 
syntax for the keys function is keys (List [Void] ) . 

FIGURE 49 shows an example of the keys function: 



FIGURE 49 



keys Function Example 



keyed . keys () --> "10", u 20", "30", "40", "50", "60", "70", 

"80", "90", "100" 
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7.1.2.26 integers Function 

The integers function generates a list of integers from the minimum to 
maximum. This is used as a general looping mechanism when combined 
with \hzfor_each function. The syntax for the integers function is inte- 
gers < integer , integer ) . The following are examples of how the 
integers function works: 

integers (1, 5) -> integers (1, 5) = 1, 2, 3 y 4, 5 

integers (5, 4) -> integers (5, 4) =4, 5 

integers (5, 5) -> integers (5, 5) =5 



integers (5, 6) -> integers (5, 6) = 5, 6 
FIGURE 50 shows an example of using integers within an expression: 



FIGURE 50 



integers Function Example 



integers (1, 3 ). for„each (echo (#. string) ) ; //returns 1, 3 




7.1.2.27 key Function 

The key function returns a key definition for use by the multijcey func- 
tion. The syntax for the key function is key ( Symbol , Symbol , Logi- 
cal , Logical ) . 

FIGURE 5 1 shows an example of how the key function works: 



FIGURE 51 



key Function Example 



define (keyl, key ("item", l.name, # . name != "leg", TRUE) ; 
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7.1.2.28 multijcey Function 

The multijcey function returns a list of key definitions for use by the 
multijceyedjist and multijcey Jbucketize functions. The syntax for the 

multijcey function is mu 1 t i„key ( Symbo 1 , Vo i d ) . 

FIGURE 52 shows an example of using the multijcey function: 



FIGURE 52 multi_key Function Example 




define(mk, mul t i_key ( w I tern" , keyl , key ( "where" , #. owner . name , #. owner 
.name I = "CANADA" , TRUE) ) ) ; 



7.1.2.29 multLkeyedJist Function 

The multijceyedjist function returns a multiple-keyed list of lists of ele- 
ments. The syntax for the multijceyedjist function is 
multi_keyed_list ( List [Void], List [Void] , Expression). 

FIGURE 53 shows an example of using the multijceyedjist function: 



FIGURE 53 multi_keyed_list Function Example 



define (mkl, item_list . mul ti_keyed_list (ink, #.name, #. category, 
# . del ivery . name ) ) ; 
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7.1 .2.30 multi_keyed_element Function 

The multijteyed_element function returns a list of elements stored at the 
specified location(s). The syntax for the multi_keyed_element function is 
multi_keyed_element (List{Void] , Integer, Symbol, Symbol). 

FIGURE 54 shows an example of using the multi_keyed_element func- 
tion: 



FIGURE 54 multi_keyed_element Function Example 



mkl . mu 1 1 i_key ed_el emen t (2 , "where" , "USA" ) ; 

Here we get the list of all the #.category that were stored for all site.names == "USA 



7.1.2.31 key_names Function 

The key_names function returns the list of key names used to build a 
multi_keyed_list or multijceyjbucketize list. The syntax for the 
keynames function is key_names (List [Void] ) . 

FIGURE 55 shows an example of using the key_names function. 




FIGURE 55 key_names Function Example 



mkl . keynames ( ) = "item", "where" 
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7.1.2.32 key_values Function 

The key_yalues function is used to retrieve the list of unique key values 
for the given name used to build a multijceyedjiist or 
multijkeyjbucketize list. The syntax for the keyjyalues function is 
key„values (List [Void] , Symbol). 

FIGURE 56 shows an example use of the key_yalues function: 



FIGURE 56 key_values Function Example 




mkl . key_values ( "item" ) = "table", "chair", "seat' 



7.1.2.33 multi_key_bucketize Function 

The multi_key_bucketize function returns a multiple-keyed and 
date_ranged (bucketized) list of lists of elements. The syntax for the 

multi_key_bucketize function is mu 1 1 i_key_bu cketize ( L i s t [ Vo i d ] , 
List [Void], List [Date_Range] , Expression, Expression). 

For examples on using the multi_key_bucketize function refer to the 
bucketize and multi_keyed_list functions. 

7.1.2.34 multi_key_bucketize_element Function 

The multi_key_bucketize_jelement function returns a list of the element(s) 
stored at the specified location(s). The syntax for this function is 

multi_keyed_bucketize_element (List[Void], Integer, Date, 
Symbo 1 , Symbo 1 ) . 

For examples on using the multi__key_bucketize function refer to the 
bucketize and multi_keyed_list functions. 
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7.1.2.35 bucket Jist_by_date Function 

The bucket J,ist_by_date function retrieves the whole list of values in the 
date_range bucket that the given date falls within. It returns a list of val- 
ues organized by key (i.e. the same kind of list that conies results from 
keyed Jisu and therefore usable by keyed^element, and keys). The syntax 
for this function is as follows: 

bucket_list_by„date (List [Void], Date) 

FIGURE 57 shows an example of using the bucket Jiistjby_date func- 
tion: 



FIGURE 57 bucketjist_by_date Function Example 




b_example.bucket_list_by_date (date ("95/01/06 00:00")) -->6, 7, 8, 9 



7.1.2.36 bucket_iist_by_key Function 

The bucket _list_by_key function retrieves the whole list of values in all 
the date_range buckets that match the given key. It returns a list of values 
organized by key (i.e. the same kind of list as comes out of keyed_list, 
and therefore usable by keyed_element, and keys). The syntax for this 
function is shown below: 

bucket_list_by_key (List [Void] , Symbol) 

FIGURE 58 shows an example use of the bucket _list_by_key function: 



FIGURE 58 bucket J ist_by_key Function Example 



b_example . bucket_list_by_key ( " 8 " ) 

.keyed_element (date_range ( "95/01/06 00:00 / 95/01/10 00 : 00 "). string) --> 
b_example . bucket_list_by„key ("8") 

,keyed_element ( "95/01/06 00:00 / 95/01/10 00:00") --> NOTHING 
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7.1.2.37 current_depth Function 

The current_depth function returns the current depth of a (recursively) 
replicating cell. The syntax for this function is current_dcpth (Cell) 

FIGURE 59 shows an example of using the current jiepth function: 



FIGURE 59 



current_depth Function Example 



current_depth (Cl ) 
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7.1.2.38 do, define, and do_file Functions 

The do function (do (expri{ , expr2 ,....})) executes the expressions 
listed sequentially left to right. It returns the value of the last expression 
evaluated as the value of the do. 

The define function (define ( temporary, expression) ) sets temporary 
to the value of the expression, define is used inside a do function. When 
writing a define function, treat temporary as a variable that is only visible 
in the containing do function. 

A do_file is a collection of OIL expressions, separated by semicolons, 
that are evaluated sequentially. They are usually written with a An or bat 
extension. The do^Jtle function (do_f ile ( filename) ) runs each expres- 
sion in the file in text order. This function is commonly used in startup 
files. The do _Jile function is also used in debugging (returns the last thing 
it evaluates in the do_file statement). When used for debugging, the 
do _Jile ("-") function invokes an OIL "listener" in the window where the 
engine was invoked. However, this function works best when not using 
the +stdout option to redirect scp_engine messages to a text file (as we 
do in runoil.cmd). 



The "listener" reads, compiles, and executes the OIL expressions you 
have typed in. It then echoes the results. You can use define to create 
temporary values within the OIL "listener" which enables you to build 
complex calculations more easily. The figure above shows some expres- 
sions being processed by the OIL "listener". Note: In .../application.rpt, 
the <ShiftxF12> key chord is bound to do_file("-") 9 so that from an OIL 
scp_ui, the "listener" can be interactively invoked by typing 




<Shift><F12>. 
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Note: Functional worksheets are the preferable method of creating OIL 
scripts (i.e. collections of OIL computations that can be invoked from 
batch clients). However, do and docile can also be used for this purpose, 
for instance, in engine startup files. 

BEFORE: 

@if ( ! button, 

do ( i f ( user . verbose , 
do (define (dash_line, 

» " £ 

» ■ ) , 

echo (dash_line) , 
echo (dash_line) , 

echo ( "Starting Auto-Reschedule at: " & hour(nowO) 
.string & " : " & minute (now ()). string & " : " & 
second (now () ) .string) , echo (dash_line) , 
echo (dash_line) ) , nonexistent) , 1 ) ) ; 

AFTER: (Create the file verbose _reportfws like this) 

function verbose^report (String message) 
{ 

[ Al dash_line = " " & 

» _ » ; ] 

[ A2 blank_line = " " ; ] 
[ A3 = echo (blank__line) ; ] 
[ A4 = echo (blank_line) ; ] 

[ A5 = echo ( "\t \t Engine Size: " & string (memory_size/ 

1048576) & "Mega Bytes"); ] 
[ A6 = echo (blank_line) ; ] 
[ A7 = echo (blank_line) ; ] 
[ A8 = echo (dash_line) ; ] 

[ A9 = echo (message & " at : " & hour (now ()). string & " : " & 

minute (now ()). string & ":" & second (now ()). string) ; ] 
[ A10 = echo (dash_line) ; ] 
[All = echo (dash_line) ; ] 
[ A12 return = 1; ] 
} 

And replaced the do above (BEFORE) with this: 

if (!button f 

if (user . verbose , 

call ( " $ 1 2_REPORTS /my^cu s t / verbos e_r epor t " , 
"Starting Auto- Reschedule" ) ) ) ; 
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7.1.2.38.1 Nested Scope in do and do_file 

Variables (temporaries) in do and dojile functions have nested scope. 
Variables defined in one do can be accessed by another do nested with 
the first (e.g. do (define <abc, 3) , do(echo(abc + 2) ) ) ;). Variables 
defined in one dojile can be accessed by another dojile started from the 
first. For example, 

do„f ile pFirstFile" ) ; 

where the contents of the FirstFile are: 

define (abc, 3 ) ; 
do_file("SecondFile") ; 

and the contents of the SecondFile are: 

echo ( abc + 2 ) ; 
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7.1 .3 Axis Cross Layouts 

The axis cross layout provides a tabular display of replicating cells. It can 
display a Cartesian cross-product of rows and columns. Since the layout 
is based on replicating worksheets, table rows or columns can have titles. 

7.1.3.1 Definitions 

The layout consists of the following elements: 

■ the X and Y axes - for values from replicating cells that determine the 
rows and columns 

■ the Cross - the product of values to be displayed across the X and Y 
axes 

Cells in the rows or columns may be grouped to allow information to be 
displayed compactly. 

7.1 .3.2 Axis Cross Layout Syntax 

Axis cross layouts require a specific syntax. This syntax is illustrated 
below: 

axis_cross layout_naine { 
worksheet: ws_name ; 
X: row specification <CROSS>; 
Y: column specification <CROSS>; 
CROSS: cross specification; 
< layout properties >; 

[ cell specification; ] 

} 

In specifying the axis cross layout, the following rules must be remem- 
bered: 

■ The cross is specified either in the X-axis or the Y-axis, never both. 

■ A cell may appear either in the X-axis or the Y-axis, but never both. 

■ If there is a cross, both axes must be present. Cells in one axis cannot 
depend on cells in the other axis. 
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7.1 .3.3 Axis Cross Layout Display 

The axis cross layout defines how the information is displayed. The cells 
in the X-axis specification run across the rows (e.g. x : ai , bi ,- displays 
all the Al then Bl). The cells in the Y-axis specification run along the 
columns (e.g. y : ai , bi ; displays all the Al then the B 1). If CROSS is 
in the X-axis specification, the CROSS cell titles run along the rows. If it 
is specified in the Y-axis, then CROSS cell titles run along the columns. 
If CROSS is defined, but is not specified in either axis, it appears along 
the Y-axis by default. Cross values always appear. However, cross titles 
appear only if the CROSS is included in an axis specification. 

In the specification y : ai , bi ; , even if B 1 is independent of Al , all val- 
ues of Bl will be displayed every time a value of Al is displayed. The 
default layout behavior is to display sparsely. Therefore, all values of 
successive rows and columns are nested under the values of the preced- 
ing rows and columns. This behavior can be changed by setting the 
sparse layout property to false. Both behaviors are illustrated in FIGURE 
60. Note: Cells are never nested in the cross. 



FIGURE 60 



Sparse Property Example 



Site 


Operation 


SI 


Oil 




012 


S2 


021 




022 




023 



Site 


Operation 


SI 


Oil 


SI 


012 


S2 


021 


S2 


022 


S2 


023 



Sparse set to True 



Sparse set to False 
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The ordering of data within the axis cross display may be controlled 
using the sort layout property, sort is only available in axis cross layouts. 
For example, the expression sort : ai -bi E2 sorts ascending first on 
cell Al, then descending on Bl, then ascending on E2. As another exam- 
ple, in the Strategy Editor's goals tab, the goals are sorted first by focus 
value, then by the name of the goal. Reducing focus on a goal moves that 
goal up to a higher row in the table (try this interactively!). (Note: This 
example can be found in ..JgoalJList.lyt.) 

7.1.3.4 Axis Cross Layout Groups 



Axis cross layouts can specify groups. If information from independent 
cells is to be displayed, groups allow generating a more compact display. 
Grouped cells are printed in a single row or column. All the values of the 
first cell in the group are followed by all the values of the second cell, etc. 
Groups may be independent or dependent. 
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7.1.3.4.1 Independent Groups 



Independent groups have cells that are not dependent on any cell in the 
group. The title from each member of the group is displayed in a separate 
row or column prior to the group values. The syntax required for this 
specification is as follows: 

(<"title cell"> group cells) 

The title cell specifies the title to be displayed for the group values col- 
umn or row. For example, refer to the file .. ./calendar _entry_list.lyt. 
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7.1.3.4.2 Dependent Groups 

In dependent groups, all cells are dependent on a different member 
within an independent group that precedes the dependent group in the 
axis specification. There is no separate column or row for the group cell 
titles since only group cell values are displayed. The syntax for depen- 
dent group specification is as follows: 

[<"title cell"> group cells] 

The title cell specifies the title to be displayed for the group values. 
Dependent groups are rarely used at present. 

7.1 .4 Tips for Working with Axis Cross 

The following tips are provided for working with axis cross: 

■ In your worksheet, give all the cells aliases and use them. This will aid 
in managing the complexity of the replicating worksheet. 

■ Get in the habit of drawing the cell dependency graph 

• It helps you detect (and break) cycles. 

• It helps you understand compiler error messages. 

• It helps you keep things straight in your mind. 
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Importing and Exporting Data 



This section introduces you to exporting information from RHYTHM 
SCP in the form of ASCII text, importing information (without much 
emphasis on the GUI), and using batch-style processing. Batch-style pro 
cessing is a means of using RHYTHM SCP's engine without the GUI. 

Exporting is one simple way of communicating from RHYTHM SCP to 
other applications; the RhythmLink product line enables more sophisti- 
cated and integrated communications between RHYTHM SCP and other 
applications. 

Importing is a form of communicating from other applications to 
RHYTHM SCP. Data is imported into RHYTHM SCP from data files. 
This imported information enables this display of information in the GUI 
and planning. 

8.1 Export File 

An export file is the layout/worksheet combination used for exporting 
data from the engine to ASCII files. It is similar to the import worksheets 
in structure and usage. The layout is called export_file layout and is 
based on the axis cross layout mechanism. This allows replicating work- 
sheets to be used to store the data that is to be exported. All export files 
have a .exp extension. 
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8.1 .1 Export File Syntax 

An export file requires a specific syntax. The required fields are shown in 
bold. This syntax is shown below: 

export_file filename 

{ 

< options > 

< file: pathname; > 

worksheet () { //a replicating worksheet 

worksheet definition; 

} 

Y: cell specification; 

} 

To use an existing worksheet instead, use worksheet : 
worksheet_name ; . The worksheet must be present in one of the reports 
directories accessible by the user. 

8.1.2 Export File Options 

Export file options are listed below: 

■ filename : "pathname" ; - the output file defaults to filename, dat 

m delimiter : "character" ; - the field delimiter to be used in the out- 
put file 

■ {bef ore_export | af ter_export } : "command" ;- the command to 

be executed before and after the export 

■ f ixed_width : true | false; - If true, the output is in fixed width 
format 

■ title_line_pref ix: "character"; - the character to be used to 

distinguish the title line from others 
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8.1.2.1 Output Cells 

The cell specification defines which cells from the worksheet will be 
exported, using the axis cross idiom. For example, in FIGURE 61 
meta_model.exp exports to mmnew.dat: 



FIGURE 61 Output Cells Example 




For each type of model in RHYTHM SCP, for each field of that model, 
one record will be exported containing the name of the model. For exam- 
ple, Buffer, and the type, name, and description of a field (e.g. Buffer, 
String, description, "description of the Buffer", Buffer, Location, loca- 
tion, "Location of the Buffer", etc.). 
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8.1 .3 .opt Files - Revisited 

.opt files are used to specify startup option settings to scp_ui and 
scp_engine. The location of .opt files can be explicitly specified by 
option _Jile flag (e.g. scp^engine option_file too/ 
scp_engine . opt). scp_engine options can be used to perform startup 
planning activities as well as to set server parameters. scp_ui options, 
however, can only set various client parameters. 

An example of the contents of scp_engine.opt and startupAn are shown 
below: 



include : 



startup: do_file ( "startup . in" ) 



scp__engine.opt 



import ( "demand" ) ; 

define (PLAN, supply_chains . first . plans . first) ; 
PLAN. site_plans . f or_each ( # . requests) . f or_each 
( # . plan_to_satisfy ) ; 

do_f ile ( n other_startup_initializations" ) ; 



startup.in 



8.1 .4 Export Directories 

In any export directory, you can place files named before ^export. in and 
after_export.in that allow RHYTHM SCP to do OIL pre- and post-pro- 
cessing upon export. For example, in the above startup. in file, upon 
invoking export ( w demand" ) , the export function first looks for a file 
named before _export.in in the demand directory, and processes it as 

do_f ile { tt demand / be f or e_expor t . in" ) . It then processes all the .exp 

files. Finally, the export function looks for a file named afte reexport. in 
and processes it as do_f ile ( n demand / af ter^expor t . in" ) , 
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8.2 import File 

Import files are layout/worksheet combinations that describe how the 
data is to be loaded into the model. Import files have a .imp extension. 
Data flies (,dat) contain the information that is loaded by the Amp files, 

8.2.1 Import File Syntax 

Import files require a specific syntax. All expressions must end with a 
semicolon. Required fields are bolded. The syntax is shown below: 

import_t ext_f i 1 e_buf f e r s 

{ 

file: "buffers.dat" ; 
delimiter: ; 

worksheet ( ) 
{ 

model : "Buffer" ; 

sf_const Supply_Chain SUPP = f ind ( supply_chains , 
Trios" ) ; 

sf_const Site SITE = find ( SUPP . sites, w Main_Link " ) ; 
this = SITE.buf f ers; 

[Al: #;] 
[Bl: #;] 

[CI : name = Al ; ] 
[Dl: location = Bl;] 
[El: description = #;] 
[Fl: flow_j?olicy = # ; ] 
[Gl : item = #; ] 

[HI: producing_operation = #;] 
[H2 : consuming^operation = #;] 
[II: min_on_hand - #;] 
[ Jl : min_time - # ; ] 

} 

import„record: Al Bl El Fl Gl HI H2 II Jl ; 

} 

The order of evaluation for the cells is not determined by cell address. 
The import ^record option specifies the order of evaluation. 
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8.2.2 Import File Options 

Import file options are as follows: 

■ file : <f iiename> - the name of the .dat file that contains the infor- 
mation to be loaded by the import file (required field) 

■ delimiter : <character> - the field delimiter to use (required field) 

■ model : <modei name> - the import file's target depth within the mod- 
eling hierarchy 

■ sf_const - the local constants for the import file 

■ this - the submodel list which is added to by the import file 

■ import„record - the order in which the fields are read from the . dat 



8.2.3 Import Directories 

In any import directory, you can place files named before ^import in and 
after Jmport An that allow RHYTHM SCP to do OIL pre- and post-pro- 
cessing upon import. For example, in the above startup.in file, upon 
invoking import ( w demand" ) , the import function first looks for a file 
named before jimport. in in the demand directory, and processes it as 
do„f ile ( " demand/ be f or e_import . in" ) . It then processes all the Amp 
files. Finally, the import function looks for a file named after _import An 
and processes it as do_f ile ( "demand/af ter_import . in" ) . 



file (this field is not required; no data is read if the field is omitted) 
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8.2.4 Ports 



On startup, scp^engine specifies a port number for network communica- 
tions (TCP/IP). Prospective clients wishing to communicate with that 
particular scp_engine must specify that port number. If they are on a dif- 
ferent machine, they must also name the host on which the scp_engine is 
running. If a port number is not explicitly specified, one is chosen by 
default (271 1 1). If port 0 is specified, then the scp__engine will start, per- 
form any planning functions specified in the startup options, and then 
automatically shut down. Example uses are pre-processing to create a 
saved memory image, or functional testing. 
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This appendix describes a scenario whereby you add a new workbench to 
the UL This scenario is provided to give you an idea of the steps you 
must perform in customizing the UL You can take the information and 
knowledge you gain here and apply it to other customization efforts. 

A.1 Overview 



In this scenario, you are adding a new workbench to the Ul named 
"Training Workbench". This workbench has one folder and the folder 
has two actions defined. The actions defined for this folder are: 

■ Bring up a new screen using OIL reports 

• Action: Launch a form to show a list of items 

• Report gives a list of items and item descriptions 

• Filters in the workbench decide which are to display 

• Right-clicks on columns of the new report allow access to standard 
reports 

■ Launch an external application 

• Action: Launch an external application (notepad.exe) 

The following are the steps (which are described in detail later) that you 
perform during this customization scenario: 

1. Write the OIL files to display Item and Item Descriptions and place 
these files in your custom_reports directory. 

2. Add an action to launch "Training Workbench" to the action table. 

3. Add the actions for launching the OIL reports and the external applica- 
tion to the action table. 

4. Add the workbench details (folders and action names) to the work- 
bench table. 

5. Add "Training Workbench" to the View menu. 

6. Add the attributes of the new report that is being launched to the 
attributes table. 
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A.2 Step 1 : Add the OIL Files 



The first step you must complete is writing the OIL files required to dis- 
play the Item and Item descriptions. These files must be placed in your 
custom_reports directory. Examples of the .rpt, Jyt, and .wrk files 
required are shown below: 



cust_item_list . rpt 

cust_item_list (String supply_chain_name , String site_name, 
String workbench_f ilter , String dummy) 

{ 

variable itms = make„type (nonexistent , List [ Item] ) ; 

compute dum_itms = define(itms, if (logical (workbench_f ilter) , 



user . selected_items , 

do (define (sc , supply__chains . f ind ( supply_.chain__name) ) , 
define (site, sc. sites . find (site_name) ) , 
site . items) ) ) ; 



layout: cus t__item_list ( itms ) ,- 
} 



cust_item_list . lyt 

axis__cross cust_item_list 
{ 

worksheet : cus t_i tem_l i s t ; 

Y: A2 Al B2 B3 B6 ; 

} 



cust_item_lis t . wrk 

replicating cust__item_list (List [Item] itms) 
{ 

[Al item = itms; 

[A2 site - item. owner;] 

[B2 = item, description; ] 

[B3 = item„category; ] 

[B6 - item_artif icial ; ] 

} 
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A.2.Q.1 Functional Worksheet Example 

The VB UI provides an action to call functional worksheets. The func- 
tional worksheet should be placed in your report path (preferably in your 
custom_reports directory) as specified in user.dat. The following exam- 
ple explains how to create a functional worksheet and the action required 
to execute it. 

The purpose of the following functional worksheet is to generate a plan 
to satisfy a request give the supply chain, plan, site and request. If * is 
sent through for requests and sites, then all requires in all the sites are 
planned. This functional worksheet is placed in your custom jreports 
directory as defined in user.dat. 

function satis fy_requests (String sc_str, String pln__str, 
String site_str, String req_srt) 

{ 

[Al SUPP = s\ipply_chains . f ind ( sc_str ) ; ] ; 
[Bl PLAN = SUPP . plans . find (pln__str ) ;] ; 

[CI SITEPLANS = if (site_str == "*", PLAN . site_plans , 
PLAN. site_plans . f ind(SUPP . sites . f ind ( site_str ) ) 
.recurse (# .members) ) ; ] ; 
[Dl dummy - if(req_str == "*", 

do (SITEPLANS . f or_each(# . p 1 an_t o_s a t i s f y_al l_r eque s t s ) , 
nonexistent) , do (SITEPLANS . for_each ( # . requests ) 
. f ind ( req__str ) .plan__to_satisfy , nonexistent) ) ;] ; 
[Fl return_dp = SITEPLANS . first . requests . first 
. delivery_requests . first . item_requests . first 
. delivery_plan . string . echo ; ] ; 
[Gl return_date = SITEPLANS . first . requests . first 
. delivery_requests . first . i tem_requests . first 
. delivery_plan . dates . string . echo ; ] ; 

} 
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The following action, i2ExecuteSatisfyRequests, is required for execut- 
ing the functional worksheet above. This action needs the following 
parameters set in xaction_editor: 



Field 


Value 


Action Name 


fws 


Action Object 


satsify_requests 


Action Command Type 


i2System.clsStdFws 


Action Params 


String context.Supply_Chain, String context.Plan, 
String contextSite, "*" 



Now, this action can be invoked as a right-click menu item or as a work- 
bench node. 
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A.3 Step 2: Add Action to Launch the Workbench 

The second step you must take is adding the action to launch the "Train- 
ing Workbench" to the action table. You need to assign a unique name to 
the action (i2DisplayWorkbench_TR in this case). To do this, use the 
xaction^editor. The following steps show how to display the 
xaction_editor and add the action to the action table: 

1. At a prompt, type the following: 

. . ./scp_ui port #### user "<NT userid>" initialize 
'display_report (xaction_editpr" , & 

The window displays. 

2. Right-click within the editor to display a popup menu. 

3. Select the New Row option. 

4. Complete the details of the action for launching the "Training Work- 
bench'^ adding the following values to the action table: 



Field 


Value 


Action Name 


i2DisplayWorkbench_TR 


Action Type 


form 


Action Object 


frmWorkbench 


Action Command Type 


i2System.clsStdForm 


Action Params 


"WorkbenchFiltersJVIP" 


Action Title Const 


Training Workbench 



Note: Several of the fields that are relevant to an action for launching 
a report are left blank. 
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A.4 Step 3: Adding the Other Actions 



The third step you must perform is adding the other actions necessary for 
launching the OIL report and the external application to the action table. 
To do this, perform the following steps: 

1. Using the xaction_editor, complete the details for the following 
actions: 

• Launching the item listing/description report 

• Running the external application (Notepad.exe) 

2. Add the following values for the action to launch the report: 



Field 


Value 


Action Name 


i2DisplayItemListingTWB 


Action Type 


form 


Action Object 


frmGenericReport 


Action Command Type 


i2SystemxlsStdForm 


Action Params 


String context.Supply_Chain, 
String context. site, 'True", 
String system.time 


Action OIL Rpt 


cust_item_list 


Action OIL Lyt 


cust_item_list 


Action Title Const 


Item Listing 


Action Tbl Name 


IL 


Action Context 


Supply_Chain, Plan, Site 


3. Add the following values for the action to launch 
tion: 


Field 


Value 


Action Name 


i2DisplayNotepadTWB 


Action Type 


exe 


Action Object 


c:\WINNT35\notepad.exe 


Action Command Type 


i2System.clsStdExe 
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A-5 Step 4: Add the Workbench Details 



The fourth step in this process is to add the workbench details (folders 
and action names) to the workbench table. To do this, follow these steps: 

l. Display the xwb_editor by typing the following at a prompt: 

. ../scp_ui port #### user "<NT userid>" initialize 
> display_report (xwb_edi tor " , «*")' & 



2. 
3. 
4. 



The window displays. 

Right-click within the Xwb Editor to display a popup menu. 
Select the New Row option. 

Add the folder "Examples" by creating a row called 
i2DisplayWorkbench_TR-Category-Examples. The following values 
must be defined for this folder: 



Field 


Value 


WB Key 


i2DisplayWorkbench_TR 


WB Type 


Category 


WB Name 


Examples 



5. Add the action required to launch the report by creating a row called 
i2DisplayWorkbench_TR-Node-ItemListing. The following values 
must be defined for this action: 



Field 


Value 


WB Key 


i2DisplayWorkbench_TR 


WB Type 


Node 


WB Name 


Item Listing 


WB Parent 


Examples 


WB Action 


i2DisplayItemListingTWB 


WB Action Type 


form 


WB Sequence 


1 


Action Context 


Supply_Chain, Plan, Site 
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6. Add the node to launch the executable by creating a row called 

i2DisplayWorkbench_TR-Node-Notepad. The following values must 
be defined for this node: 



Field 


Value 


WB Key 


i2DisplayWorkbench_TR 


WB Type 


Node 


WB Name 


Notepad 


WB Parent 


Examples 


WB Action 


i2DisplayNotepadTWB 


WB Action Type 


exe 


WB Sequence 


2 



A-8 RHYTHM SCP Customization Manual 



March 27, 1998 © 1998 i2 Technologies, Inc. Proprietary Information 




Customizing the VB Ul Step 5: Add the Workbench to the Menu 



A.6 Step 5: Add the Workbench to the Menu 

The fifth step you must perform is adding "Training Workbench" to the 
View menu. To do this, follow the steps below: 

1. Display the xmenu_actions_editor by typing the following at a 
prompt: 

. . ./scp__ui port #### user "<NT userid>" initialize 
'display_report (xmenu_actions_editor" , w * " ) ' & 

The window displays. 

2. Right-click within the editor to display a popup menu. 

3. Select the New Row option. 

4. Define "Training Workbench" as a new menu item of the View menu 
and associate an action with it by performing the following: 

l. Add a new row called "Workbench-Training Workbench". The 
following values must be defined for the action of launching 
this workbench from the View menu: 



Field 


Value 


Menu Name 


Workbench 


Menu Item 


Training Workbench 


Menu Caption 


&Training Workbench 


Menu Action 


i2DisplayWorkbench_TR 


WB Action 


i2DisplayNotepadTWB 
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A.7 Step 6: Add the Attributes 

The sixth and final step in this process is to add the attributes of the new 
report that is being launched in the attrib_definiiions.dat file. 
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Appendix b Hints for Writing Effective OIL 



The ability to write OIL effectively is important for using RHYTHM 
SCP software. This appendix lists some helpful hints for writing OIL 
effectively and efficiently. 



B.1 Basic Improvements 



This first section provides some basic ways in which you can improve 
your efficiency. 

B.1 .1 Minimizing List Creation 

In order for you to use memory efficiently and get the best performance, 
put subsequent list manipulation functions inside the original function's 
(). For example, consider the following OIL expressions which give the 
same answer and where in is a list of plans: 

in.for_each(# . sites) . for_each (# . operations ) . filter (...)... 
in . f or„each ( # . sites . f or_each ( # . operations . filter ( ...)))... 

Which expression is better? 

FIGURE 62 shows what is really happening in the first OIL expression. 



FIGURE 62 List Creation Example 1 

in. for„each(# . sites) for_each(# . operations) . filter (...)--. 

. r . h "; — i, — ^ — , 

For every plan in list in, creates a ...and for every site in the new ...and from the new operations list, 
copy of the sites list... sites list, creates a copy of the creates another list of operations! 

operations list... 



When the datasets arc large, this is clearly a time and memory hog! 
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FIGURE 63 shows what is really happening in the second OIL expres- 
sion. 



FIGURE 63 List Creation Example 2 

in. for_each(# . sites . f or_each (# . operations . filter (...)))... 



For every plan in list in... 



...retrieves the existing sites 
list for the plan, and for every ▼ 

site... ...retrieves the existing operations list for the site, 

and from that list, creates a new list of operations. 

Obviously uses less memory than the first expression ! 



Also important in the minimization of list creation is refraining from fil- 
tering through lists when you know the end product For instance, do not 
search through a list of operation plans if you already know the operation 
you need. Instead, get the list of operation plans from the operation. 
Therefore, rather than using the following expression: 

site_plan. operation_plan . filter ( # . operation = = 
myoperation) f or__each ( ...)... 

use this expression instead: 

myoperation . opera tion_plans ( site_plan . plan) 
f or__each (...)... 

Another element in minimizing list creation is using a previous variable 
rather than re-creating a similar list when you are defining more than one 
variable in a worksheet. For example, instead of using the following 
expressions: 

fool = f oo__plan . seller_plans . f or_each 

( # . forecasts . for_each ( # . entries . for_each 
( # . planned) ) ) . sum 

foo2 = f oo_plan . seller_plans . f or_each 

(♦forecasts . for_each ( # . entries . f or__each 
( # . committed) ) ) . sum 
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use these expressions for enhanced efficiency: 

foo - foojplan. seller_plans . for_each 

( # . forecasts . for_each ( # . entries ) ) 

fool = foo . f or_each ( # . planned) . sum 

foo2 = f oo . for_each (#. committed) . sum 
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B.1.2 Preserving Hierarchy Information 

When you need to filter a list of information and you intend to show the 
results with a hierarchy control (e.g. outline ^general, indented ^general), 
put the filter expression inside the recur se. For example, consider the 
following OIL expressions, each of which generate lists with the same 
elements, but only one of them has hidden hierarchy information that 
certain controls can use: 

in . recurse ( # . sub_operat ions . filter (..-))-•- 
in. recurse ( # . sub_operations) . filter (...)... 

FIGURE 64 illustrates whether or not the first OIL expression results in 
hierarchy information. 



FIGURE 64 Preserving Hierarchy Information Example 1 

in. recurse (#. sub_operat ions . filter ( ...)))... 

' 1 " — I — ' 

Creates a list with hierarchy information... y 

...then creates a list without 
hierarchy information... 

This expression's result list has no hierarchy information. 



FIGURE 65 shows that the second OIL expression does have hierarchy 
information. 



B-4 RHYTHM SCP Customization Manual 



March 27, 1998 © 1998 i2 Technologies, Inc. Proprietary Information 





Hints for Writing Effective OIL Basic Improvements 



FIGURE 65 Preserving Hierarchy Information Example 2 

in . recurse ( # . sub_operations . filter (...))) 

1 -i. 1 

Creates a list without hierarchy information... 



...then recursively creates a list with hierarchy information... 

This expression's result list has hierarchy information. 
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B.1 .3 Caching Values for Reuse 

Cells sometimes have common sub-expressions. You can improve mem- 
ory use and performance by caching the result of the common sub- 
expression. For example: 

[ Al allocation^ ill_rate = plan . seller_plans . 

f or_each ( # . produc t_forecasts ) . f or_each 

(#. entries) . filter (and (#. committed > 0, 
#. committed != #. allocated) ). filter 

(percentage (# .allocated/# . committed) < 
percentage ( 80 )) ; ] 
[ A2 allocation_consumption_rate = 
plan . seller plans . for_each 

( # . product^f orecasts ) . f or_each 

(# .entries) . filter (and (#. committed > 0, 

#. committed != #. allocated) ) . 

filter (and (#. allocated > 0, percentage 

( ft . consumed/ # . allocated) < 
percentage ( 5 0 ))) ; ] 

The following is better because it only creates the list for the common 
sub-expression once: 

COMPUTE interesting^entries = 

plan . seller_plans . f or_each 

( #.product_f orecasts) . f or__each 

(# .entries) . filter (and(#. committed > 0, 

#. committed != #. allocated) ) ; 
[ Al allocation_f ill_rate - 

interesting_entries . filter (percentage 

(#. allocated/# . committed) < 

percentage ( 80 )) ; ] 
[ A2 allocation_consumption_rate - 

interesting_entries . filter (and 

(#. allocated > 0, percentage (#. consumed/ 

#. allocated) < percentage ( 50 ))) ; ] 

Many times the worksheets in a report need to share information. Always 
try to put the shared information in the report and pass it to all the layouts 
that need it, instead of recomputing the same information on each tab. 
You may find that you can actually share the worksheets with a few small 
additions. This will not necessarily save you time, but will help when you 
are optimizing. 
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B.1 .4 Do Not Concatenate String Values 

It is important for performance to generate string values once per replica- 
tion rather than concatenating the same strings over and over in loop iter- 
ations. For example: 

[B2 : PLAN, si te__plans. find (SITE) . 

operation_plans . filter (or (or 

( # . release_name = = rel & "Prod", 

# .release_name == rel & "Cons"), 

# . release_name == rel) ) . for_each 

(do (# . set_ord_id(ord) id) , 

# .set_qty (qty) , # . set_log (TRUE) , 

nonexistent) ) ; ] 

The problem with the expression above is that the same string values are 
created for every element of the list. To improve performance, you 
should use the following expression: 

[B2: do (define (relprod, rel & "Prod"), 
define (relcons , rel & "Cons"), 
PLAN.site_plans.find(SITE) . 
operation_plans . filter (or (or 
( # . release_name relprod, 
# . release_name == relcons), 
# . release_name == rel ) ) . f or^each ( do 
(# . set_ord_id(ord_id) , # . set_qty (qty) , 
# . set_log (TRUE) , nonexistent) ) ) ; ] 

Or, if rel does not change values during the life of the worksheet (e.g. rel 
is passed as a parameter), the following expression would provide greater 
performance since the strings would only be generated once: 

variable relprod = rel & "Prod" ; 
variable relcons = rel & "Cons"; 
[B2: PLAN. si te_plans . find (SITE) . 
operation_plans . filter (or (or 
( # . release_name = = relprod, 
# . release_name — relcons), 
#.release__name == rel ) ) . f or_each ( do 
( # . set„ord_id (ord„id) , # . set_qty (qty) , 
# . set_log (TRUE) , nonexistent) ) ) ; ] 
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B.1.5 Getting the Index of the Current Iteration Element 

When you iterate over a list, you refer to the current element as #; how- 
ever, sometimes you need to know the index of the current element as 
well. That is, you need an OIL equivalent of a for loop. A pseudo-code 
example would be: 

for (i = 1 to num) { 

printPLoad i &" is"); 

print {OPERATION. loads (i) .name, ... 

} 

The OIL solution for this is to use the integers function and iterate over 
the list of integers. For example, given a list of loads for an operation: 

[ Al = integers (1, num) . for_each( "Load 

w & #. string &" is" & OPERATION . loads . 
element (#)). string ( "newline" ) ; ] 

Cell Al will show the following string: 

Loadl is Heavy_Load 
Load2 is Light_Load 
Load3 is Medium Load 
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B.1.6 Iterating through Multiple Related Lists 

When you have lists where the nth element in each list goes together, you 
can synchronize a loop over the elements by using the integers func- 
tion. For example, given the following lists: 

wordsl ==> list (" fruit" , "tree", "heavy") 
words2 ==> list ("Apple, "Limb", "Cargo") 
words3 ==> list ("is a", "is part of a", "is") 

create strings such as "Apple is a fruit". 

The OIL solution to iterating through multiple related lists is the judi- 
cious use of the integers and element functions. For example, 

integers { 1 , 3 ) . for_each (words2 . 

element (#) & " " & verbs . element {# ) & " " & 
wordsl . element (#) ) ==> list ( "Apple is a fruit", 
"Limb is part of a tree", "Cargo is heavy") 

Note that the code above simply assumes that wordsl, words2, and verbs 
all have 3 elements. To handle same-size lists of arbitrary length, you 
should use the count function. 

integers ( 1 , verbs - count) . f or_each (...) 
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B.1.7 Sorting on Multiple Keys 

The sort function is simple to use. But what if you want a list sorted by 
more than one key? The OIL solution is as follows: 

sort ( if (a . primary _key != b .primary_key , 
a ,primary_key < b . primary_key , 
a . secondary_key < b . secondary _key) ) ; 

For example, sort a list of operation plans by start dates (primary key). If 
any of them start on the same day, sort those operations alphabetically 
(secondary key). The OIL expression is as follows: 

SITEPLAN. operation_plans . sort (if 

(a . operation . date b . operation . date , 
a . operation . date < b. operation . date, 
a . dates . name < b . dates . name ) ) ; 

B.1 .8 Empty Initial Values 

Variables are normally initialized with meaningful data. However, some- 
times you need to initialize a variable to an empty list or nonexistent. 
This causes problems when you need to write a cell expression that relies 
on the type of the value. You should use make_type to circumvent this 
problem. 

FIGURE 66 shows an example of an expression that the compiler will 
not like and one that the compiler will like: 



FIGURE 66 Empty Initial Values Example 

VARIABLE chosen_operation = nonexistent; 
[ Al = chosen_operat ion . sub_operat ions ; ]; 

Since the type of chosen_operation is unknown, the compiler cannot detect which sub_operations function to use. 



VARIABLE chosen_operation - mak e_ type (nonexistent , Operation) ; 
[ Al = chosen_operat ion . sub_operat ions ; ]; 

The type of chosen ^operation is specified here, and the compiler can detect which sub ^operations function to use. 
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B.1 .9 Symbols vs Strings 

A string is a simple vector of characters. Strings are not shared. If the 
same string is used 50 times within RHYTHM SCP, it takes 50 times as 
much memory as one string. Most description fields in the RHYTHM 
SCP Model Reference Manual are strings because they are rarely shared. 

A symbol is a shared string. Symbols are interned in a hash-table, so if 
the same symbol is used 50 times with RHYTHM SCP, it only takes up 
storage equal to one string (plus 3 words of overhead). Another advan- 
tage of symbols is that equal symbols have the same address in memory, 
which makes the "==" and "!=" operators for symbols much faster. Most 
model names in the RHYTHM SCP Model Reference Manual are sym- 
bols, to avoid duplication and make comparison faster. 

The distinction between strings and symbols is important when deciding 
on the data-type for a user-defined field. 

■ Use symbol where you can take advantage of sharing 

■ Use string when the contents are probably unique 

Avoid converting symbols to strings in the UI when you do not need to. 
For example, 



B.1.10 for_each 

Do not makefor_each work harder than necessary. For example, 

lists . for_each(#. listb) . for__each(# . listc) 
takes longer than 

lists . f or_each (# .listb. for_each ( # . listc) ) 
The time is computed for every layer of nesting. 



list_of_buf fers . for_each(# . string) ; 

//makes a list of name STRINGS 

list_of_buf fers . f or_each (# .name) • 

//makes a list of name S YMBOLs 
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B.1.11 if 

You should reduce the logical computation of if statements where possi- 
ble. For example, 

[B4 = ATP_SP.operation__plans . filter 

(#. released True) . filter (# .motive == 
"DELIVER") . filter (#. item, name == 
A2 . name ) . for_each ( # . uni ts ) . 
sum ? number ( " 0 " ) ; ] 

is better than: 

[B4 = i f ( foo . foo_plans . filter (#. released == 
True) . filter (# .motive == "DELIVER" ) . 
f ilter (#. item. name == A2 . name ) . 
f or_each ( # . units ) . sum. exists . not , 
number ( w 0 " ) , foo . f oo_plans . filter 
(#. released == True) . filter (# .motive == 
"DELIVER") . filter (#. item. name == A2.name). 
f or_each ( # . uni ts ) . sum) ; ] 

B.1.12 filter and sort 

You should always perform filter before sort. As an example, you 
should use the following expression: 



foo = fool . filter ( f oo2 ) . sort (a . sort_qty < 
b. sort_qty ) ; 



rather than this expression: 



foo = f ool . sort (a . sort_qty < b.sort_qty). 
filter (foo2) ) ; 
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B.1.13 Do Not Compute Unnecessarily 

Reports have to react to changes, but you can minimize the recomputing 
that takes place. For example, you could use: 

compute a - plan . si te__plans . 
for^each ( # . requests ) ; 

However, the following OIL code is much more efficient: 

variable current_plan = plan; 
variable a = plan . site. plans . 

for_each (#. requests ) ,- 
compute check_plan = if (current_plan plan, 

current_plan , do ( set_variable (a, 

. si te_plans . f or_each ( # . requests ) ) , 

set_variable ( current_plan , plan) ) ) ; 

Then, the list will only be recomputed if the plan changes. 

Do not compute something, then discard it with an if. Instead, check the 
condition up front to avoid the computation. For example, some reports 
have options to select what RHYTHM SCP displays. 

Do not compute the intermediate results if the final result is known to be 
nonexistent. Also, do not loop through a large list filtering out something, 
then loop around this inner loop using a different filter criterion. Instead, 
loop through the list once gathering together the different data in a single 
pass. This is what bucket! ze does, for instance. 

The following examples show a poor way and a better way to compute 
information: 

foo = fool . sort ( a . sort_qty < b.sort_qty) . 



filter (foo2) ) 



foo 



= fool, filter (foo2) . sort (a. sort_qty < 
b . sort^qty) 
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In the set of examples above, the second expression is much more effi- 
cient to the first expression. 

[ B4 - if ( foo . foo_plans . filter (#. released == 
True) . filter (# .motive == w DELIVER" ) . 
f ilter (#. items . name == A2 . name) . f or_each 
(#. units) . sum. exists .not , number ("0") , 
foo . foo plans . filter { # . released == 
True) . filter (# .motive = = "DELIVER" ) 
. filter (#. items . name == A2 .name) . 
for_each (# .units ). sum) ; ] 

[ B4 = ATP_SP.operation_plans . filter 

(#. released == True) . filter {#. motive == 
"DELIVER" ) .f ilter (#. items. name == 
A2.name) . for_each (#. units ) .sum ? number 
("0"); ] 

In the set of examples above, the second expression if more efficient than 
the first. 



B.1.14 And, Or are Short-Circuits 

The logical operators and and or perform short-circuit evaluations. Once 
the and operator finds a value that returns false, it returns false and stops 
evaluating. Once the or operator finds a value that returns true, it returns 
true and stops evaluating. So, you can gain some speed wins by using and 
and or when you filter. 

For example, using the expression from previous section you can 
improve its efficiency by adding the and operator: 

[ B4 = ATP_SP.operation_plans . filter (and 

(#. released == True) . filter (#. motive == 
"DELIVER") . f ilter (#.i terns. name == 
A2.name) . for_each (#. units ) .sum ? number 
("0"); ] 

In general, you should: 

■ Put the clause that will return false most often first in the and list 

■ Put the clause that will return true most often first in the or list 
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B.1.15 Using bucketize 

You should use the bucketize function to gather different data from a 
large list rather than looping through a huge list filtering for some data, 
then looping around this inner loop using different filter criteria. As an 
example, consider the following expression: 



compute buckets = msp_seller . 

seller_plan (plan) . produc t_f orecas ts . 
for_each ( # . entries) .bucketize (bucket_list , 
# . delivery_dates . start , #. owner . 
product . name) ; 



B.1.16 Finding Problem Areas 

If you have a worksheet that seems to be taking a long time to come up, 
try running the scp_engine with the timings option. Given a number as a 
parameter (e.g. timings 5 0) the timings option will print out the calcula- 
tions in the worksheet that take longer than 50 milliseconds. This will aid 
you in finding the cells and expressions that are causing problems. 
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B.2 Performance Tuning 

Several performance problems can occur when using OIL, such as: 

■ reports coming up too slowly 

■ reports updating too slowly 

■ import files processing too slowly 

■ batch files running too slowly 

■ UI response time too slow 

These problems are caused by bottlenecks such as: 

■ excessive use of computes 

■ not separating common subtasks 

■ expressions not calculated by underlying code 
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B.2.1 Using Option Files 

One way to improve the engine's performance is to use option files. 
Option (.opt) files allow you to track problems and to optimize the 
engine. The following is an example scp_engine.opt file: 

scp_engine . opt 

seed: l 

command_execute : true 

action : true 

diagnostic: true 

absolute_pathnames : true 

stdout : true 

dont„dispose_com_var_val : true 

debug : true 

timing: 200 

memory: 1000000 

command„usage : last queue elapsed, last 

run elapsed, last reply elapsed 

command_usage__f ile : 

The command_execute option returns every command (time, user, etc.). 
You can track problems easier using the last four options. The 
dont_dispose_com_var_val option allows you to keep computed values. 
The debug option is the OIL debugger. The timing option is set to milli- 
seconds and the memory option is set to bytes. The command_usage 
option keeps a log of the specified items in milliseconds. The 
command jmsagejile echoes to stdout. 

Note: Refer to the section Engine and UI Options on page 26 for more 
information on .opt files and a list of all engine and UI options. 

B.2.2 Timing and Memory 

The timing and memory engine options are used to track performance. 
They report engine time only (only the time it takes on the CPU). The 
options must be used together. If you use only one, the engine returns 
every memory allocation. Note: When using these options, the dependent 
times are cumulative so you have to subtract to get the exact value for a 
particular expression. 
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B.2.3 Mem metrics 

Mem„metrics tracks exactly what kinds of memory are allocated and 
where they are allocated. This allows you to look at a "snapshot" of 
memory allocations and see what is taking a large amount of memory and 
what is not. The options for mem_metrics are: 

■ mprof_metrics - displays memory usage after the process has allocated 
some amount of megabytes 

■ default_metrics_percentage - defines how much of the allocated mem- 
ory to display (if no specification, returns 80%) 

■ mprof - turns on the recording of memory usage information 

■ mprofjog - provides a "dump" of memory usage information to a file 
in order to produce a graph 

The following is an example of an option file (scp_engine.opt) using 
mem_metrics: 

tips_test \ 

option_file scp_engine . opt \ 
open x3 1 . saved \ 
startup_file start21675 . in \ 
default_metrics_percentage 100 \ 
mprof _metrics 10 \ 
mprof 1 \ 

mprof_log blp_p lan„x4 4 . memory .log \ 

system $l2_HOME/ tests/blp/system \ 

absolute_pathnames \ 

port 5619 \ 

+stdout \ 

| tee 21675.log 

The I tee 21675.log command echoes the stdout, but rather than running 
in an emacs shell, this outputs to a file that you can bring up in emacs and 
compare the result. 

When trying to find a memory growth problem, use the memjMjin juse 
option. This option prints information for every piece of memory it can 
track. 
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B.2.4 Common Pitfalls 

Some common pitfalls to try to avoid when using OIL are: 

■ redoing subtasks instead of storing the result 

■ overlooking the case where a value is nonexistent 

■ using if instead of the existence operator "?" 

■ using list operations out of optimal sequence (filter, for_each, sort) 

■ refiltering instead of using booleans (filter using and instead of using 
multiple filters) 

Some time consuming expressions are: 

■ operation. super__operations - very slow because it does not cache 

■ buffer.all_consuming_operations and buffer. all_producing_operations 

■ find_or_create - prepares to create before finding 

■ contains - cannot make any assumptions about a list it is working on 
so it does an exact instance match 

■ date arithmetic - if you must use this expression, set the time at the top 
of the file rather than in the middle of a complex computation 
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OIL Debugger 



C.1 



C.2 



i2 has created a debugger for use with OIL. This section provides an 
overview of OIL Debugger, the functions associated with it, and some 
example uses of it. 

OIL Debugger Overview 



OIL Debugger is a simple interface and uses an OIL Listener. When 
stopped at a breakpoint, an OIL Listener is entered. The OIL Listener 
reads from scp_engine's standard-in and writes to standard-out. You will 
see an "odb>" prompt when OIL Debugger is active. You can enter any 
OIL expression at the prompt and see the evaluation results. Note: Enter- 
ing an empty line causes the previous command to run again. This is 
handy for running the next, step, or cont functions repeatedly. 

OIL Debugger and scp_eng ine 

You cannot run scp_engine in the background and use these debugging 
aids. You can run scp_engine in an emacs shell buffer instead. This way 
you can use meta-p to recall previous commands, you get an infinite his- 
tory, and it is easy to cut and paste. Note: All breakpoints default to dis- 
abled if the debug option is FALSE (which is the default). Breakpoints 
default to enabled when the debug option if TRUE. Breakpoints can be 
controlled through the Breakpoint model. See the enable and disable 
functions. 
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C.3 OIL Debugger Functions 

The following functions were added to OIL for debugging purposes. 
Note: Optional parameters are in square brackets [ ]. 

■ break([expression, [, name [, condition]]]) 

■ breakpoint^, name]) 

■ stop(cell_name [, worksheet_name]) 

■ enable[(breakpoint_name)] 

■ di sable [(breakpoint„name)] 

■ next[(count)] 

■ step[(count)] 

■ cont[(count)] 

■ watch([expression [, name [, condition]]]) 

■ unwatch(watchpoint_name) 

■ where 

■ whereis 

■ print„variables 

■ print_report_variables 

■ inspect(any_model) 

C.3.1 break Function 

The break function (break (Expression result, Symbol name, 

Expression condition) ) executes the first parameter, returning its 
value. It also creates a Breakpoint model for the expression. 

If no parameters are specified, the current list of breakpoints is printed. 
The first parameter can be of any type, and is the result from this func- 
tion. The second parameter is the optional breakpoint name (the default is 
a small integer). Note: There can be multiple breakpoints with the same 
name. All are enabled and disabled together, have the same condition, 
etc. The third parameter is an optional breakpoint condition which must 
evaluate to TRUE before breaking, condition is evaluated before express 
sion. 
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C.3. 2 breakpoint Function 

The breakpoint function either creates a breakpoint or finds a breakpoint 
with a particular name. For example, 

breakpoint ( ) / / creates a breakpoint 

breakpoint (Symbol name) // finds or creates a 

/ / breakpoint with the 

/ / name " name " 

C.3.3 stop Function 

The stop function either creates a breakpoint for the named cell and 
worksheet or creates a breakpoint for the named cell in the current work- 
sheet. See the break function for more details. For example, 

stop (Symbol cell__name, Symbol worksheet_name ) 

// creates a breakpoint for the named 
// cell and worksheet 

stop (Symbol cell___name) // creates a breakpoint for 

/ / the named cell in the 

// current worksheet 

C.3.4 enable Function 

The enable function enables the specified breakpoint or all breakpoints. 
For example, 

enable () // enables all breakpoints 

enable (name) // enables the breakpoint 

/ / named "name" 

C.3.5 disable Function 

The disable function disables the specified breakpoint or all breakpoints. 
For example, 

disable () // disables all breakpoints 

disable (name) .// disables the breakpoint 

/ / named w name " 
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C.3.6 next Function 

The next function runs until the next cell, do^file line or variable assign- 
ment. It does not cross into other call or do_file files. (See step for more 
details.) When you use the parameter count, it specifies the number of 
breakpoints to skip before actually stopping. 

C.3.7 step Function 

The step function runs until the next cell, do_file line or variable assign- 
ment. It will step into other call or do_file statements. (See next for more 
details.) When you use the parameter count, it specifies the number of 
breakpoints to skip before actually stopping. 

C.3.8 cont Function 

The cont function continues until the next breakpoint. When you use the 
parameter count, it specifies the number of breakpoints minus one to skip 
before actually stopping. 

C.3.9 watch Function 

The watch function creates a watchpoint model object that executes the 
expression and prints the results at every breakpoint executed in the same 
context as watch was executed in (the same worksheet or do_file). 

If no parameters are specified, the current list of watchpoints is printed. 
The first parameter can be of any type, and is the result from this func- 
tion. The second parameter is the optional watchpoint name (the default 
is a small integer). Note: If there is already a watchpoint with the given 
name, its expression and condition are replaced with new definitions. The 
third parameter is an optional watchpoint condition which must evaluate 
to TRUE before printing, condition is evaluated before stuff. 

If the third condition parameter is nonexistent (the default) the watch- 
point prints only when the results are different than the last time. To print 
every time, use TRUE for the condition. 

C.3.10 un watch Function 

The unwatch function removes the named watchpoint model object (cre- 
ated by watchpoint). Its first parameter is the name of the watchpoint to 
delete. If the name is all, then all watchpoints are deleted. 
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C.3.11 where Function 

The where function returns a one-line description of where this function 
is executing. 

C.3.12 whereis Function 

The whereis function prints a detailed description of where this function 
is executing. 

C.3.13 print variables Function 

The print_variables function prints all the variables and their values. 

C.3.14 print report_variables Function 

The print_report_variables function prints all the report variables and 
their values. 
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C.3.15 inspect Function 

The inspect function allows you to inspect any of the following: 

■ any model, displaying all its fields and sub-models 

■ any list 

■ all extension selectors 

■ all extended fields 

■ all user-defined fields 

You can drill down into the model using the inspects, inspectH or 
inspectHS functions. 

The inspect function's parameters include any model, or list[model]. It 
allows you to drill down into a field (or list of fields) displayed by the 
previous inspect* call. 

The inspect function numbers the fields it prints. The inspects function 
(inspects (int i tem_number ) ) takes one of these numbers as its 

parameter. The inspectH function (inspectH ( int history^number ) ) 

recalls a previously inspected value. Each time one of the inspect* func- 
tions is called, the first line shows a history number. Using that number 
as its parameter, inspectH prints the same inspection again. The 

inspectHS function (inspectHS (int history_number, int 

fieid^nuniber) ) allows you to drill down into a field (or list of fields) of 
a previously inspected value. inspectHS uses the numbers from inspectH 
and inspects as its parameters. 

The inspects/ functions are for use with calling other OIL functions on 
values that have previously been inspected. The first inspectV function 
(inspectv ( int field_number)) returns the value of a field from the 
last inspected model or list. It uses a number (derived from inspect num- 
bering the fields it prints) as a parameter. The second inspectV function 
(inspectV (int history_number, int f ield_number ) ) returns the 
value of a field from the last inspected model or list. This version of the 
inspectV function uses the same parameters as the inspectHS function. 
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C.3.16 Customizing Debugger Prompt 

The OIL Debugger prompt can be customized using the debug_prompt 
option. For example: 

set_option ( "debug_prompt" , "Break { 0 } >" ) 

This expression will use the breakpoint name in the prompt (e.g "Break 

3>"). 

C.3.17 Setting Breakpoints in startup.in 

To set a breakpoint in your startup An file, you must manually insert the 
break function in your OIL code. 

C.3.18 Setting Breakpoints in do_file 

To set a breakpoint in a do_file, edit the file to add a break function. For 
example: 

if (or (exact (st_str , "* " ) , exact (end_str, "*")), 
define (d_r, PLAN. horizon) -break, 

define (d_r, date_range (date(st_str) , date (end„str) ) ) 

) ; 



or: 



if (or (exact (st_str, " * " ) , exact (end_str, "*")), 

define (d_r , PLAN. horizon) . break ( n some_name " ) , 

def ine (d_r , date_range (date (st__str) , date ( end_s tr ) ) ) 

) ; 



or: 



if (or (exact (st_str , "*") , exact ( end_str , "*")), 
define (d_r , PLAN . horizon) . break ( n some name n , 
site== n f oo" ) , 

define (d_r , date_range (date (st_str) , date (end_str ) ) ) 

) ; 

In the first example, a breakpoint is created by adding .break. In the sec- 
ond example, a named breakpoint is added. In the third example, a condi- 
tional breakpoint is added. 
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C.3.19 Disabling/Enabling Breakpoints 

To disable a breakpoint, type the following: 

disable ( "name" ) 

where name is the name of the breakpoint. If name is all, then all break- 
points are disabled. 

To enable a breakpoint, type the following: 
enable ( "name" ) 

where name is the name of the breakpoint. If name is all, then all break- 
points are enabled. 
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Ul Design Principles and 




Philosophy 



There are several things to keep in mind when designing your UI depend- 
ing on what you are trying to accomplish. This appendix attempts to list 
some of the more important general guidelines to follow: 

■ Keep the system's behavior consistent. The same class of object 
should generate the same type of feedback and resulting behavior, not 
matter where it appears. For example, 

• a checkbox always changes the value of the toggle; it may invoke 
side effects associated with the value that has changed (e.g. changing a 
site from managed to unmanaged), but it does NOT pop up a list of 
choices like a combo^popdown or move the window like a scrollbar. 

• a scrollbar always scrolls the contents of a window; it does NOT pop 
up a dialog or flash the screen. 

• a user presses a button to make something happen; the button never 
"presses itself in response to some internal function call, or acts like a 
checkbox. 

m Pick the appropriate control for the task at hand. Deciding can be 
tricky when controls do similar things (e.g. combo _popdown and a 
group of radiojbuttons both select one value from a small set of 
known values). 

• If a cell is editable and possible values are a small set (<10) and 
known ahead of time, a group of radio_buttons is a good choice. 

• If a cell is editable and possible values are limited (<15), then a 
combo __popdown is a good control. 

• If the number of possible values is more than a few and dynamic, use 
mechanisms to permit the user to choose instead of typing (such as 
model _choose) . 

■ By design a control does only one thing. For example, a label is 
designed to display text using a certain style. So adding a select action 
to a label that causes it to bring up a report is making that label behave 
as if it were a button; this is surprising and unintuitive behavior to the 
user. 

■ Buttons do something; that is, they make the software actually per- 
form some function. 
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m Flashy colors are great for demos but absolutely horrible for day-to- 
day use. 

• Highly saturated colors are easiest to see, and hardest to look at for 
long periods of time. 

• Use 3 to 4 colors at most (charts, graphs, and images are exceptions). 

■ Assume that errors will happen and provide ways to negotiate them. 

■ Avoid cascading menus. IF you must cascade menus, only put items 
that are used less often in the submenus, and never use more than 3 
levels. 

• The ergonomics involved are too tricky, and puts the user into mental 
gymnastics to remember the desired UI item's location. 

■ Help the user know what data is being displayed in a report; include a 
context header. 

• Many are provided in the standard reports directory; reuse when pos- 
sible, and follow their style if you have to create a new one. 

■ Important functionality should never have a hidden mechanism as the 
only means of invoking it. 

• For example, since the right-click popup menu is a hidden mecha- 
nism, anything that is available in that menu should also be available 
through regular menus in the menubar. 

■ Minimize the learning curve. 

• Use the same names/terms/phrases throughout the interface. If you 
call it a demand channel in one place, call it a demand channel in all 
places. 

• To the extent that is feasible, use industry and/or customer-specific 
terminology. 

• Make use of the common UI idioms you have become familiar with 
as a 1990's computer user (e.g. Save always goes under the File menu, 
and dialogs always have a Cancel or Close button). 
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The following is a list of images provided in RHYTHM SCP. Note that 
these are subject to change without notice. 



add_column 


find_down 


add_row 


fmd_down_right 


alternate 


fmdjeft 


around_left 


find_Jeft_up 


around_over 


fmd_right 


around_right 


find_right_down 


around_under 


fmd_up 


bar_chart 


find_up_left 


buffer 


flow 


buffer_in 


forecast 


buffer_out 


freeze 


calendar 


freeze_report 


choose 


gantt_chart 


close 


help 


close_report 
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Common Worksheet Definition 



Appendix F 



Axis Cross Examples 



This appendix provides examples of axis cross layouts. 



F-1 Common Worksheet Definition 



The following worksheet definition is used in most of the axis cross 
examples that follow. 

Disclaimer: All of these examples were lifted directly from internal tests; 
that means the data are contrived. 



replicating cross ( ) 
{ 

variable alist = list ("a" 

variable blist = list("l" 

variable clist = list("x" 

variable dlist = list ("7" 

variable elist = list ("7" 

// Cell Dependency Graph 
Al CI 




x 2" , "1", "2", "3", "1", "2") 

*8" , "9" , »7" , "8" ) ; 

v 8" , "9", "nonexistent", "8") 



Kl 



[ Al resource = alist; ];// Independent 

[ Al .title = "Al" ; ] ; 

[ A2 = Al ; ] ; 

[ A2. title = "A2"; ] ; 
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} 



[ B2 alts = if(Al=="A", blist . sublist ( 1 , 2 ) , // F(al) 

if (Al=="b", blist .sublist (3 ,3) , 
blist. sublist(6, 2) ) ) ; ] ; 

[ B2 . title = "B2" ; ] • 

[ Bl = Al & B2; ] ; 

[ Bl . title - "A&B" ] ; 

[ CI = clist. sublist (1,2) ; ]; // Independent 

[ CI . title = "CI"; ] ; 

[ C2 = CI; ] ; 

[ C2 . title = "C2" ; ] ; 

[ D2 - if(Cl = ="x", dlist. sublist (1, 2) , // F(cl) 

dlist .sublist (3, 3) ) ; ] ; 

[ Dl = Cl & D2 ; ] ; 

[ Dl. title - "C&D"; ] ; 

[ El = Bl & Dl ; ] ; 

[ El . title = "B&D" ; ] ; 

[ Fl = upper- (El) ; ] ; 

[ Fl. title = "upper (E)"; ]; 

[ Gl = elist ; ] ; 

[ Gl. title = * Range Test"; ]; // Tests copying of ranges, 

and ranges with nonexistent 
members 

[ HI = list ("") .sublist (2,2) ; ]; // Empty list 

[ HI. title = "HI"; ] ; 

[ II = HI; ] ; 

[ II. title = "II"; ] ; 

[ Jl = if (exists (II) , "exists-", "nonexis ts- " ) & Dl ,- ]; 
[ Jl . title = "I & D" ; ] ; 

[ Kl = "Doh!"; ]; [ Kl. title - "Homer"; ]; 

C K2 = nonexistent; ]; [ K2. title = "Nonex2"; ]; 

[ K3 = nonexistent; J; [ K3. title = "Nonex3 " ; ]; 
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Example Set A 


F.2 Example Set A 





The following sections illustrate axis cross layouts in several formats. 



F.2.1 Example Layout 1 

This example shows a fairly typical axis cross with items in the X, Y and 
CROSS. In this case, the cross is in the Y-axis. 



axis_cross cross_test 
{ 

no_scroll: true; 
worksheet: cross; 
sort: -cl; 
cross: El, Fl; 
X: cl, dl; 

Y: al , cross; // Leave out Bl to test the case where a 

// replicator that doesn't compute a list 
// is not displayed, but it's a 
// dependency of something that 
// IS displayed. 
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F.2.2 Example Layout 2 

This layout shows an axis cross without a scroll bar and the cross defaults 
to the Y-axis. 

axis_cross cross_testlb 
{ 

no_scroll: true; 

worksheet: cross ; 

X: cl; 

Y : al ; 

cross: El; 

} 
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F.2.3 Example Layout 3 

This example shows an axis cross with the cross displayed in the X-axis 
and no scrollbar. 

axis_cross cross_testld 
{ 

no_scroll: true; 

worksheet: cross; 

X: cl cross ; 

Y: al; 

cross: El; 

} 
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F.2.4 Example Layout 4 

This axis cross example has items in the X, Y and CROSS. The cross is 
displayed in the Y-axis, and there is no scrollbar. 

axis_cross cross_testle 
{ 

no_scroll: true; 
worksheet: cross; 
X: kl cl k2; 
Y: al cross; 
cross : El ; 
} 



111 



Doh! 
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F.2.5 Example Layout 5 

This axis cross contains items in the X, Y, and CROSS. The cross dis- 
plays in the Y-axis, there is no scrollbar displayed, and sparse is set to 
false (see the section on Axis Cross Display in OIL Lesson 5). 

axis_cross cross_test2 
{ 

no_scroll: true; 

worksheet: cross; 

X: cl, dl; 

Y: al , Bl cross; 

cross : El ; 

sparse: false; 

} 
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F.2.6 Example Layout 6 

This example of axis cross has items in the X, Y, and CROSS. In this 
case, the cross is shown in the Y-axis. 

axis_cross cross_test2b 
{ 

no_scroll: true; 

worksheet: cross; 



y 

x 



cl c2 cross; 
al; 



cross : bl dl ; 
> 
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F.2.7 Example Layout 7 

This axis cross example contains items in the X, Y, and CROSS. The 
cross is shown in the X-axis along with two other elements. No scrollbar 
is present. 

axis„cross cross_test3a 

// Cross and 2 elements in the x axis 
{ 

no_scroll: true; 
worksheet: cross; 
x: cl c2 cross; 
y : al b2 ; 
cross: bl dl ; 
} 
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F.2.8 Example Layout 8 

This example of axis cross also contains two elements and the CROSS in 
the X-axis. Again, no scrollbar is present. 

axis_cross cross_test3al 

// Cross and 2 elements in the x axis 

{ 

worksheet: cross; 
no^scroll: true; 
x: cl cross c2 ; 
y: al b2 ; 
cross: bl dl ; 
} 
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F.2.9 Example Layout 9 

The following axis cross example contains items in the X, Y, and 
CROSS. The X-axis holds two elements and the CROSS. No scrollbar is 
present and sparse is set to false (see the section on Axis Cross Display in 
OIL Lesson 5). 

axis_cross cross_test3a2 

/ / Cross and 2 elements in the x axis 

{ 

worksheet : cross ; 
no_scroll : true; 
x: cross cl c2 ; 
y: al b2; 
cross: bl dl ; 
sparse: false ; 
} 
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F.2.1 0 Example Layout 1 0 

This axis cross has items in the X, Y, and CROSS. The cross is displayed 
in the X-axis. There is no scrollbar present in this example. 

axis_cross cross_test3a3 
{ 

no_scroll : true; 

worksheet : cross ; 

x : cross c2 ; 

y: al b2 ; 

cross: bl dl; 

} 
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F.2.1 1 Example Layout 1 1 

This example shows a layout with the CROSS and one element in the X- 
axis. Items are also specified in the Y, and the CROSS. No scrollbar is 
present and sparse is set to false (see the section on Axis Cross Display in 
OIL Lesson 5). 

axis_cross cross_test3a4 
{ 

no_scroll : true; 
worksheet : cross; 
x: cross cl; 
y: al b2 ; 
cross : bl dl ; 
sparse: false; 
} 




© 1998 i2 Technologies, Inc. Proprietary Information March 27, 1998 



RHYTHM SCP Customization Manual F-13 




Example Set A Axis Cross Examples 



F.2.1 2 Example Layout 1 2 

This example has the CROSS and two elements in the X-axis. The Y-axis 
and CROSS also contain items. There is no scrollbar and sparse is again 
set to false (see the section on Axis Cross Display in OIL Lesson 5). 

axis_cross cross_test3a5 

// Cross and 2 elements in the x axis 

{ 

no_scroll: true; 
worksheet: cross; 
x: cross c2 cl ; 
y: al b2; 
cross : bl dl ; 
sparse: false; 
} 
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F.2.13 Example Layout 13 

This layout shows an axis cross with no items specified for the Y-axis 
(Y-axis empty). The cross is displayed in the X-axis and no scrollbar is 
present. 

axis_cross cross_test3a6x 

// empty y axis 

{ 

no_scroll: true; 
worksheet: cross; 
x: al bl cross; 
cross: el; 
} 
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F.2.14 Example Layout 14 

This example illustrates an axis cross with a combination of cross titles 
defaulting to the Y-axis and an empty Y-axis (no items in Y-axis). 

axis_cross cross_test3a6xe 

// combo of cross titles default to y axis and 

empty y axis 

{ 

no_scrol 1 : true ; 
worksheet: cross; 
x: al bl ; 
cross: el; 
} 
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F.2.15 Example Layout 15 

This axis cross layout displays an empty X-axis. There are items in the Y 
and the CROSS. No scrollbar is present. 

axis_cross cross_test3a6y 

// empty x axis 

{ 

no_scroll: true; 
worksheet: cross; 
y: al bl cross ; 
cross : el; 
} 
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F.2.16 Example Layout 16 

This example is more typical of axis cross having items in the X, Y, and 
CROSS. Again, no scrollbar is present and the cross is displayed in the 



X-axis. 

axis_cross cross_test3b 
{ 

no_scroll: true; 
worksheet: cross; 
x: cl c2 cross; 
y: al; 

cross: bl dl ; 
} 
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F.2.17 Example Layout 17 

This example shows an axis cross with only the CROSS contained in the 
X-axis. No scrollbar is present. 

axis_cross cross_test3c 

// Only the cross in the x axis 

{ 

no_scroll: true; 
worksheet: cross; 
x: cross; 
y: al; 

cross: bl dl ; 
} 
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F.2.1 8 Example Layout 1 8 

This axis cross example shows, again, a layout with only the CROSS in 
the X-axis. 

axis_cross cross_test3d 

// Only the cross in the x axis 

{ 

no_scroll: true; 
worksheet: cross; 
x: cross; 
y: al b2; 
cross: bl dl ; 
} 
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F.2.19 Example Layout 19 

This example (shown on the next page) shows an axis cross with group- 
ing (see Axis Cross Layout Groups in OIL Lesson 5). Only the Y-axis 
contains items. 

axis_cross cross_test4 

// Grouping test 

C 

no^scroll: true; 
worksheet: cross ; 
y : al cl t>2 (bl dl) ; 
} 
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F.3 Example Set B 

The next example illustrates an axis cross layout given the following 
worksheet: 

replicating groups ( ) 
{ 

variable alist - list ("a", 
variable blist = list("l", 
variable clist = list("x", 
variable dlist = list ("7", 

[ Al resource = alist . sublist ( 1 , 3 ) ; ];// Independent 
[ Al . title = "Al" ; ] ; 
[ A2 = Al; ] ; 
[ A2 . title = "A2" ; ] ; 
[ A3 = upper (Al) ; ] ; 
[ A3. title = "upper (Al)"; ]; 

[ B2 alts - if(Al== "A", blis t . sublist { 1 , 2 ),/ / F(al) 

if (Al=="b", blist.sublist(3,3) , 
blist. sublist (6,2) )) ; ] ; 

[ B2. title = "B2"; ] ; 

[ Bl = Al & B2 ; ] ; 

[ Bl . title = W A&B" ; ] ; 

[ CI = clist. sublist (1,2) ; ] ; // Independent 
[ CI - title = "Cl"; ] ; 
[ C2 = CI; ] ; 
[ C2 .title = "C2"; ] ; 

[ D2 = if(Cl=="x", dlist .sublist (1, 2) , // F(cl) 

dlist . sublist ( 3 , 3 )) ; ]; 

[ Dl = CI & D2 ; ] ; 
[ Dl . title = "C&D" ; ] ; 
[ El - Bl & Dl ; ] ; 
[ El. title = "B&D"; ]; 

[ E2 = if (El == "aly8", list ( "yep" , "FOB"), 

nonexistent) ; ] ; 
[ E3 - if(E2 == "yep", "foo", nonexistent); ]; 
[ Fl = upper (El) ; ] ; 
[ Fl. title = "upper (E)"; ]; 
[ Gl = ""; ] ; 

[ Gl. title = "independent group title"; ]; 
[ hi = upper (dl); ]; 
[ hi. title = "upper (Dl) " ; ]; 
[ il = upper (bl) ; ] ; 
[ il. title = "upper (Bl)"; ]; 
[ Jl = ""; ] ; 

[ Jl. title = "dependent group title"; ]; 
[ Kl - nonexistent; ];[ Kl . title = "Nonexl"; ]; 



b", "c") ; 

2", "1", "2", "3", "1", "2"); 
y") ; 

8", "9", "7", "8"); 
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[ 


K2 


= nonexistent; ] , 


■ [ K2 . 


title = 


w Nonex2" 


/ J j 




[ 


K3 


- nonexistent; ], 


■ [ K3. 


title = 


"Noriex3 " 


r J * 




[ 


K4 


= nonexistent; ], 


■ [ K4. 


title = 


w Nonex4" 


/ J i 




[ 


K5 


= nonexistent; ], 


■ [ K5. 


title = 


"Nonex5" 


r i i 




[ 


K6 


- nonexistent; ] , 


• [ K6. 


title = 


"Nonex6 " 


I i • 




[ 


Ml 


= do ( Dl , nonexistent ) ; 


] 






[ 


K7 


= do (Ml , nonexistent ) ; 


] ; [ K7 . 


title = w 


Nonex7 



} 



F.3.1 Example Layout 1 

This example illustrates using independent and dependent groups in axis 
cross (see Axis Cross Layout Groups in OIL Lesson 5). 

axis_cross groups_test 
{ 

no_scroll: true; 
worksheet : groups ; 

y: al cl b2 ("gl" bl dl ) ["jl" il hi] ; 

// Independent_and_Dependent_Group_Examples - This 

// layout is an example of independent and dependent 

// groups in an axis specification. The Y axis 

// specification contains the independent group of bl 

// and dl with a title specified in gl . It also 

// contains the dependent group containing il and hi 

// with a title coming from jl. See the comment at the 

// top of this file, to run this example. 

// See : : Axis_Cross_Layout_Groups for an overview of 

// this topic. 

} 
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